# Troubleshooting

| Symptom | Action |
| --- | --- |
| Python/module missing | Use the installed client's virtual-environment Python, not another system Python. Re-run the installer if installation was interrupted. |
| No key configured | Obtain the key file independently from the owner, then `media configure --key-file PATH`. Do not paste the value in commands. |
| HTTP 401 | Key missing, invalid or revoked. Confirm configuration/environment points to the intended key. Contact the owner; do not generate a replacement client key yourself. |
| HTTP 403 | Browser Origin is not supported for the API. Use CLI or local stdio MCP. Do not use a browser app to send keys. |
| Health works but worker offline | Setup is valid. The home computer/controller is unavailable; jobs wait. Report this and avoid repeated submissions. |
| HTTP 422 | Read the validation error and live schema. Check dimensions, asset roles, voice tags, audio mode and unsupported operations. |
| HTTP 409 | Idempotency conflict or quota. A changed request needs a deliberately new key. Do not change a key merely after a lost response. |
| HTTP 413 / 429 | Input/storage limit or too many uploads; reduce input or wait. |
| Wait timed out | The job still exists. Use the same job ID to check status/wait. |
| Failed/interrupted job | Inspect diagnostics/result and report the job ID. Only deliberately resubmit after resolving the cause. |
| Missing model / OOM | Contact the owner. Do not request a different checkpoint, install models remotely or launch another GPU worker. |
| MCP absent in the agent | Run `media mcp-check`, then merge `media mcp-config` into the agent's supported MCP configuration; preserve other servers. Restart/reload the agent if its host requires it. |
| MCP handshake succeeds but generation unavailable | These are separate checks. Run `media doctor`; inspect authentication and worker availability. |
| Download checksum mismatch | Keep the job ID, retry download and report repeated failures. Do not regenerate merely because a download failed. |

Client configuration defaults to `~/.media-bridge/config.json`, with a separately
stored `client.key`. `MEDIA_CONFIG_DIR` selects another profile directory.
`MEDIA_URL`, `MEDIA_KEY_FILE` and legacy `MEDIA_KEY` override saved configuration;
unexpected inherited values can explain using the wrong server/key. Prefer files.
The MCP configuration contains only an absolute executable path and configuration
directory, never the credential value. The executable path is machine-specific.

For help send the owner the job ID, client/API version and redacted doctor output.
Do not send keys, full environment dumps or unrelated private media.