Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Troubleshooting

When a Toolang agent behaves unexpectedly, the fastest path is usually:

  1. sync again
  2. inspect the agent room
  3. verify capabilities and local configuration

Start with sync

toolang sync <agent_selector> refreshes the exact runtime inputs. If source files, refs, or local capability files changed, sync is the first command to run before debugging anything deeper.

Common symptoms that often come from stale sync state:

  • a new capability is not visible at runtime
  • an inline declaration change does not appear to take effect
  • scope overrides do not match what you expected

Inspect the agent room

For one agent, the most useful paths are:

${AGENT_HOME}/.toolang/agents/{AGENT}/
  agent.run
  agent.log
  execution.db
  pulse.json
  task_mirrors.json
  runs/
  tasks/
  chores/

Check them in this order:

  • agent.log for startup and runtime errors
  • agent.run for current process metadata
  • execution.db for durable run and turn history
  • runs/ for prompt and trace artifacts
  • tasks/ and chores/ when the problem is scheduling or recurring work

Verify capabilities and configuration

If an agent cannot see a skill, service, prompt, or psyche, check:

  • the capability name and kind
  • the selected scope
  • whether shared or global scopes are enabled for this run
  • required local credentials in .env or integration config

If a remote task provider is involved, also verify that the service capability used for task access is actually configured and has the required permissions.

Check long-lived runtime inputs

If run or start works but polling, hooks, or recurring work do not:

  • inspect channels.toml
  • inspect hooks.toml
  • inspect pulse.json
  • inspect task_mirrors.json

The usual failure modes are:

  • a loop binding is missing
  • credentials are missing
  • the chore that should mirror remote tasks is not configured
  • local task files exist, but the runtime considers them paused or inactive

Prefer local truth over projections

The shared bus and local APIs are useful, but the primary execution truth stays on disk. If a view from the API looks wrong, compare it with:

  • the synced files under .toolang/sync/
  • the agent room state under .toolang/agents/{AGENT}/
  • the global registry under ~/.toolang/agents.db

Read next

© 2026 Toolang