Skill symlink skipped as path escape

Use when logs include:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

Every skill root is a containment boundary. A symlink under ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, or ~/.apus/skills is skipped when its real target resolves outside that root, unless the target is explicitly trusted.

Inspect the link:

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
apus config get skills.load

If the target is intentional, configure both the direct skill root and the allowed symlink target:

{
  skills: {
    load: {
      extraDirs: ["~/path/to/skills"],
      allowSymlinkTargets: ["~/path/to/skills"],
    },
  },
}

Then start a new session or wait for the skills watcher to refresh. Restart the gateway if the running process predates the config change.

Do not use broad targets such as ~, /, or a whole synced project folder. Keep allowSymlinkTargets scoped to the real skill root that contains trusted SKILL.md directories.

Skill Workshop does not use these trusted discovery targets. It writes only inside the active agent's <state-dir>/agents/<agentId>/agent/workshop-skills.

Related:

• Skills config
• Configuration examples

Anthropic 429 extra usage required for long context

Use when logs/errors include: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

apus logs --follow
apus models status
apus config get agents.defaults.models

Look for:

• Selected Anthropic model has a native 1M context window (Opus 5, Sonnet 5, Mythos 5, Fable 5.1, Fable 5, Opus 4.6/4.7/4.8, Sonnet 4.6), or the model config still carries legacy params.context1m: true.
• Current Anthropic credential is not eligible for long-context usage.
• Requests fail only on long sessions/model runs that need the 1M context path.

Fix options:

Switch to a standard-window model, or remove legacy `context1m` from older
model config that is not GA-capable for 1M context.

Use an Anthropic credential that is eligible for long-context requests, or switch to an Anthropic API key.

Configure fallback models so runs continue when Anthropic long-context requests are rejected.

Related:

• Anthropic
• Token use and costs
• Why am I seeing HTTP 429 from Anthropic?

Upstream 403 blocked responses

Use when an upstream LLM provider returns a generic 403 such as Your request was blocked.

Do not assume this is always an Apus configuration issue. The response can come from an upstream security layer such as a CDN, WAF, bot-management rule, or reverse proxy in front of an OpenAI-compatible endpoint.

apus status
apus gateway status
apus logs --follow

Look for:

• Multiple models under the same provider failing the same way.
• HTML or generic security text instead of a normal provider API error.
• Provider-side security events for the same request time.
• A tiny direct curl check succeeding while normal SDK-shaped requests fail.

Fix the provider-side filtering first when evidence points to a WAF/CDN block. Prefer a narrowly scoped allow or skip rule for the API path Apus uses, and avoid disabling protection for the whole site.

Related:

• OpenAI-compatible endpoints
• Provider configuration
• Logs

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
apus infer model run --model <provider/model> --prompt "hi" --json
apus logs --follow

- `model_not_found` with a local MLX/vLLM-style server: verify `baseUrl` includes `/v1`, `api` is `"openai-completions"` for `/v1/chat/completions` backends, and `models.providers.<provider>.models[].id` is the bare provider-local id. Select it with the provider prefix once, for example `mlx/mlx-community/Qwen3-30B-A3B-6bit`; keep the catalog entry as `mlx-community/Qwen3-30B-A3B-6bit`.
- `messages[...].content: invalid type: sequence, expected a string`: backend rejects structured Chat Completions content parts. Fix: set `models.providers.<provider>.models[].compat.requiresStringContent: true`.
- `validation.keys` or allowed message keys like `["role","content"]`: backend rejects OpenAI-style replay metadata on Chat Completions messages. Fix: set `models.providers.<provider>.models[].compat.strictMessageKeys: true`.
- `incomplete turn detected ... stopReason=stop payloads=0`: the backend completed the Chat Completions request but returned no user-visible assistant text for that turn. Apus retries replay-safe empty OpenAI-compatible turns once; persistent failures usually mean the backend is emitting empty/non-text content or suppressing final-answer text.
- Direct tiny requests succeed, but Apus agent runs fail with backend/model crashes (for example Gemma on some `llama-server` builds behind `llmman`): Apus transport is likely already correct; the backend is failing on the larger agent-runtime prompt shape.
- Failures shrink after disabling tools but do not disappear: tool schemas were part of the pressure, but the remaining issue is still upstream model/server capacity or a backend bug.

1. Set `compat.requiresStringContent: true` for string-only Chat Completions backends.
2. Set `compat.strictMessageKeys: true` for strict Chat Completions backends that only accept `role` and `content` on each message.
3. Set `compat.supportsTools: false` for models/backends that cannot handle Apus's tool schema surface reliably.
4. Lower prompt pressure where possible: smaller workspace bootstrap, shorter session history, lighter local model, or a backend with stronger long-context support.
5. If tiny direct requests keep passing while Apus agent turns still crash inside the backend, treat it as an upstream server/model limitation and file a repro there with the accepted payload shape.

• Configuration
• Local models
• OpenAI-compatible endpoints