Common Errors
Solutions to the most common Yukkai errors and issues.
Overview
Running into an error with Yukkai? You're not alone. This guide covers the most frequently encountered errors, their root causes, and step-by-step fixes you can apply right away. Each entry distills real troubleshooting patterns gathered from Yukkai's diagnostic knowledge base, so you can resolve issues quickly without trial and error.
If your error isn't listed here, try asking Yukkai directly — describe what happened and the assistant will investigate.
Common Errors
| Error | Likely Cause | Fix |
|---|---|---|
| 401 Unauthorized | API key is missing, expired, or invalid. | Open the Vault and verify your OpenRouter key. Re-add the key if needed, then test a short prompt in a new session. |
| 402 Payment Required | Insufficient Wallet balance or credit limit reached. | Check your Wallet balance. Top up credits or switch to a lower-cost model. Verify the generation actually failed before retrying to avoid double charges. |
| 403 Forbidden | Your key lacks access to the selected model or provider. | Confirm the model is available on your plan. Switch to a model you have access to, or contact your provider. |
| 429 Too Many Requests | Rate limit exceeded — too many concurrent requests or calls per minute. | Reduce concurrency in swarm tasks. Wait a moment before retrying. If persistent, lower the number of parallel agents. |
| 5xx Server Error | Temporary provider outage or internal server issue. | Retry after a short wait. If the error persists, check the provider's status page. Switch to an alternative provider or model if available. |
| Agent task failed | A sub-agent hit an error — missing context, wrong role, or rate-related issue. | Inspect the failed agent result. Add the missing context or dependency. Assign a more appropriate role. If rate-related, reduce concurrency. Do not discard successful results. |
| Workflow did not run | Workflow is disabled, a required tool/model is unavailable, or a Human-in-the-Loop step is waiting. | Enable the workflow. Confirm all required tools and connections. Check whether a human approval step is pending. Review the schedule and time zone. |
| Generation failed (image/video/music) | Unsupported resolution, prompt rejected by provider policy, or network interruption. | Simplify parameters. Retry with standard resolution and aspect ratio. Review the provider's policy error text. Switch provider or model if available. Check ~/YukkaiDocs/ for any partial output. |
| Shell command timed out | Command is long-running, interactive, or waiting for user input. | Read the complete command output. Use a non-interactive command variant. Increase timeout only when safe. Run smaller steps separately. Avoid rerunning commands with side effects until prior state is verified. |
| Swarm is slow or costly | Too many agents, overlapping tasks, expensive models, or repeated restarts of failed tasks. | Reduce the number of concurrent agents. Avoid frontier/expensive models when not needed. Trim excessive shared context. Retry only failed tasks, not the entire swarm. |
| Task appears stuck | A provider request is stalled, a tool is waiting, or an agent is blocked on user input. | Check if a Human-in-the-Loop step is pending. Look for stalled provider requests. Verify the status view isn't stale. Narrow an overly broad task into smaller steps. |
| No response from model | No internet access, wrong model selected, or key/Wallet issue. | Confirm internet access. Confirm the selected model. Confirm key or Wallet balance. Test a short prompt in a new session. Switch model if the issue persists. |
| File not found / empty output | Output path is wrong or generation hasn't completed yet. | Ask Yukkai to inspect ~/YukkaiDocs/ for the generated file. Confirm the output path. Wait for the generation to finish before checking. |
How to Use It
1. Identify the error code or symptom
Start by reading the full error message or command output. Look for HTTP status codes (401, 402, 403, 429, 5xx) or descriptive failure text.
2. Match it to the table above
Find the row that matches your error. The Likely Cause column tells you what's happening behind the scenes.
3. Follow the fix steps
Apply the steps in the Fix column in order. Most fixes involve checking credentials, reducing load, or retrying with adjusted parameters.
4. Ask Yukkai if you're still stuck
If the table doesn't resolve your issue, describe the error to Yukkai. The assistant can:
- Inspect logs and outputs automatically.
- Verify file paths and process states.
- Check Wallet balance and key validity.
- Test a minimal reproduction to isolate the problem.
Examples
Example 1: Rate limit during a large swarm
You launch a swarm with 12 parallel agents and several return 429 Too Many Requests.
Fix: Reduce concurrency to 4–6 agents. Retry only the failed tasks. The completed results are preserved — you don't need to start over.
Example 2: Image generation fails silently
You request a 4K image and nothing appears in ~/YukkaiDocs/.
Fix: First, ask Yukkai to check ~/YukkaiDocs/ — the file may have been generated but saved with a different name. If it genuinely failed, retry with 1K resolution and standard aspect ratio. Check the Wallet balance before retrying to avoid paying twice.
Example 3: Workflow doesn't trigger on schedule
Your scheduled workflow hasn't run today.
Fix: Check whether the workflow is enabled. Confirm the schedule time zone matches yours. Look for a pending Human-in-the-Loop approval step. Run the workflow manually to see if it succeeds — if it does, the issue was the schedule, not the workflow itself.
Example 4: Shell command hangs indefinitely
A bash command runs but never returns.
Fix: Read the partial output. The command may be waiting for interactive input (e.g., a password prompt). Use a non-interactive variant or pipe input via echo. Break the command into smaller steps. Increase the timeout only if the command is legitimately long-running.
Tips
- Always read the full error output. The error message usually contains the exact reason for failure — don't skip it.
- Check credentials first. Most errors (401, 402, 403) come down to key, access, or balance issues. Verify these before deep-diving.
- Retry only what failed. When a swarm or workflow partially fails, retry just the failed tasks. Successful results are kept.
- Simplify before escalating. If a generation fails, try standard resolution and simpler parameters before contacting support.
- Don't double-pay. Before retrying a paid generation (image, video, music), confirm it actually failed — the output may exist in
~/YukkaiDocs/. - Reduce concurrency proactively. If you routinely hit 429 errors, lower your default agent count.
- Keep your key healthy. Periodically check your OpenRouter key usage with the
openrouter_key_usagetool to stay ahead of limits. - Ask Yukkai to investigate. When in doubt, describe the problem in plain language — Yukkai will inspect, test, and guide you to a fix.