# Agent troubleshooting

Fix installation and API access issues.

## The installer cannot find a skill

Use the exact docs origin:

```bash
npx skills add https://docs.letsgen.app --list
```

The discovery index is [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json). It points to a digest-verified `SKILL.md`. If the index is unreachable, check network/DNS and whether the docs release is live. Updating the skills CLI may be necessary for well-known domain discovery.

## The agent cannot see LETSGEN_API_KEY

An agent inherits environment variables from the process that starts it. Restart it from the configured shell, or use its supported secret settings. Check whether the variable exists without printing its value. Never paste the secret into the conversation to diagnose it.

## 401 or 403

Use `Authorization: Bearer`, not an `apikey` header. A missing/expired/revoked secret returns 401; missing read/generate scope returns 403. A key with generate scope alone cannot discover or poll. Account and regional policies continue to apply.

## Model or settings rejected

Discover current model IDs and capabilities. Use the public ID, not a provider-specific name. Select a supported resolution/duration/ratio and use `sourceImage` for an image-to-video first frame. Uploaded references must be owned asset IDs, not remote URLs.

## Gem ceiling or monthly cap reached

`PRICE_CHANGED` refers to your request ceiling. `API_KEY_LIMIT` refers to key allowance. Reduce settings, inspect outstanding tasks, or request an explicit budget change. Do not switch keys to bypass a spending limit.

## Request timed out

Keep the original payload, API key, and `Idempotency-Key`. If you have a media task ID, read it. Otherwise replay the exact request with backoff. `REQUEST_UNCERTAIN` is not permission to create a fresh request. Support may need to investigate persistent uncertainty.

## Output link expired

Read the same task for a current signed URL and download again. Do not generate again. Retain successful output files locally.