Troubleshooting

Common failure modes and how to unstick them.

Out of credits

Symptom: Generations start failing across the board. Balance shows $0.

Fix:

1. Top up your account.
2. Record the top-up:
   stirvid record-funding --amount 100 --source manual_topup
   
3. Confirm balance:
   stirvid balance
   

Billing quota reached

Symptom: Image or video jobs fail with quota errors.

Fix: Wait for the quota window to reset, or upgrade your plan. Use stirvid status to confirm active plan and remaining allowance.

Image edit rejected by safety filters

Symptom: An image swap job returns a safety-filter rejection.

Fix: Some references or prompts are blocked by upstream safety filters. Try a different reference image, remove sensitive prompt phrasing, or reframe the composition. Credits are not deducted for rejected jobs.

MCP 401

Symptom: Every MCP call returns 401.

Fix:

• The Bearer token is wrong or was rotated. Mint a new key:
  stirvid keys:create --label "Replacement"
  
• Update the client config’s Authorization: Bearer <KEY> header.
• Restart the MCP client.

Local stack not loading

Symptom: Local development containers will not start; docker commands hang or time out.

Fix:

docker compose down
docker compose up -d

If containers still fail to start, restart your container runtime and retry.