Troubleshooting

Troubleshooting

This page lists common problems and the fastest checks.

NPM Command Does Not Start

Run:

node --version
npm --version

AgentDesk expects Node.js 20.19.0 or newer.

Try:

npx --yes --package=@papaplus/agentdesk agentdesk --port 5173

If the port is busy, choose another port:

npx --yes --package=@papaplus/agentdesk agentdesk --port 5174

Source Install Fails

From the repo:

npm install
npm run typecheck
npm test
npm run build

If install fails, delete node_modules and reinstall. Keep package-lock.json unless you intentionally update dependencies.

Browser Shows Static Demo But Runtime Is Unavailable

Static hosted builds cannot spawn local processes. Runtime mode requires the packaged CLI:

npx --yes --package=@papaplus/agentdesk agentdesk --port 5173

Then open Doctor and click Check runtime.

Ollama Does Not Run

Check:

1. Ollama is installed.
2. Ollama is running.
3. http://127.0.0.1:11434 is reachable.
4. The selected model is pulled locally.
5. The workflow has model nodes with provider: "ollama".
6. Run mode is Ollama or Runtime.

Example:

ollama pull llama3.2

Cloud BYOK Fails

Check:

1. Provider is selected correctly.
2. API key is valid.
3. Model ID is valid for the provider/account.
4. Browser-direct calls are allowed by provider CORS and organization policy.
5. Matching model nodes exist in the selected workflow.
6. Apply to nodes was clicked if you changed provider/model.

If browser-direct calls are blocked, this is expected for some environments. A production app should use a backend proxy.

MCP Discovery Fails

Check:

1. Runtime CLI is running.
2. Run mode is Runtime.
3. MCP config imports without parse errors.
4. Server id in the node matches the imported config.
5. The server command exists on PATH.
6. The MCP server uses JSON-RPC correctly over stdio.
7. The server does not print non-JSON logs to stdout.
8. Error artifacts do not contain missing env/header key names.

Try the legacy adapter if needed:

AGENTDESK_MCP_ADAPTER=legacy-jsonrpc agentdesk --port 5173

Export Contains Too Much Evidence

AgentDesk redacts common secrets, but it cannot guarantee that arbitrary text, screenshots, stdout, stderr, or model responses contain no sensitive content.

Before posting publicly:

• inspect exported JSON
• inspect ZIP contents
• remove sensitive screenshots
• redact customer data
• do not include API keys or tokens

Verification Commands

For maintainers and contributors:

npm run typecheck
npm test
npm run build
npm run test:e2e
npm run smoke:package
npm run verify
npm pack --dry-run --ignore-scripts --json