Troubleshooting

No supported agent is available

Install Codex, Claude Code, or Gemini CLI and confirm its executable is on PATH. Alternatively, print the prepared prompt and paste it into an agent session yourself:

doxloop create --print "Create a quickstart for developers adopting this product."

The agent is installed but still reports "not available on PATH"

Doxloop reports an error such as doxloop: claude is not available on PATH. even after installation when the agent's install directory isn't on your shell's PATH. Claude Code's native installer commonly places the executable in ~/.local/bin, which some shell configurations don't include by default.

Confirm the executable's location, then add its directory to PATH:

which claude || find ~/.local/bin -name claude

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

claude --version
doxloop doctor
doxloop create --agent claude

The same cause and fix apply to Codex or Gemini CLI if their install directory is missing from PATH instead.

An installed skill is modified

Doxloop never overwrites local skill changes automatically.

doxloop agent status
doxloop agent update

Review the diff before replacing an intentional customization — agent update replaces the skill unconditionally.

An external generator cannot load

Confirm both the core package and the selected generator package are installed in the documentation project, then run:

doxloop generator doctor

Native generators may also require their own runtime — Python, Ruby, Hugo, or Node — installed separately. The doctor output reports the expected build command.

Create or update exits, but synchronization isn't recorded

Doxloop withholds a new synchronization baseline when validation fails, or when create didn't save a primary audience and priority outcomes to the documentation brief. Run doxloop test, resolve every error, and rerun create or update.

Capture blocks a URL

Capture rejects an unconfigured origin, cross-origin navigation, and a private network destination by design. Add the intended public origin with --reference first:

doxloop create \
  --reference https://docs.example.com/ \
  "Use this site as a presentation reference while documenting the product."

For a trusted local reference only:

DOXLOOP_ALLOW_PRIVATE_REFERENCES=1 doxloop capture http://localhost:3000/

Guide screenshots are missing

Application screenshot capture requires the Codex or Claude desktop app and is not supported through Codex CLI, Claude Code CLI, or Gemini CLI. Prepare a screenshot-enabled prompt, then submit it from a supported desktop session:

doxloop update --screenshots --print "Refresh the affected guide screenshots."

If capture still cannot proceed, confirm that:

• application.baseUrl is reachable from the desktop app;
• application.source, startCommand, and readyPath match the local test application;
• browser access is available in the desktop session;
• authentication uses a non-production session; and
• safe fixtures or test data are ready.

Doxloop keeps the text procedure complete when capture fails. Remove broken image references and rerun the affected update after the missing condition is resolved. See Add guide screenshots.

API requests fail

Confirm the API URL uses HTTPS (HTTP is accepted only for loopback development), that the token starts with dxb_, and that the endpoint doesn't redirect. Prefer doxloop login to refresh credentials rather than reusing an old token.

Preview port is occupied

Choose another port:

doxloop preview --port 4400 --open

Validation and the native build disagree

doxloop test performs fast project and content checks; the generator's native build is the final parser for that format. Run both and treat either failure as blocking — see CI and automation.

Next steps