Skip to main content

Troubleshooting

Use this page when Faheem Code does not start, the browser cannot reach it, the backend is disconnected, model setup fails, or uninstall/update commands get stuck.

Choose your situation​

Faheem Code cannot start

The browser works but Canvas cannot reach its backend

The backend works but the model fails

You need to remove or reset Canvas

Start with these checks​

Run the checks for the install method you used:

node --version
npm --version
uv --version
faheem-code --help

If one command fails, fix that prerequisite first. See Install.

faheem-code command not found​

If faheem-code is not available after installation:

  1. Confirm the package installed successfully. You should see @faheem-code/app followed by the version if it has been installed:

    npm list -g --depth 0

  2. Check your npm global install prefix:

    npm prefix -g

  3. Make sure the npm global bin directory is on your PATH.

    Find the npm global bin directory:

    echo "$(npm prefix -g)/bin"

    Check whether your shell can already find faheem-code:

    which faheem-code

    If which faheem-code prints nothing, check your current PATH:

    echo "$PATH"

    If the npm global bin directory is missing, add it for the current terminal session:

    export PATH="$(npm prefix -g)/bin:$PATH"

    To make the change permanent, add that export line to your shell profile, such as ~/.zshrc or ~/.bashrc.

  4. Try running without a global install:

    npx @faheem-code/app

If npx works but faheem-code does not, the issue is usually your shell PATH.

Missing uv or uvx​

Faheem Code uses uv to run the local agent server stack.

If startup fails because uv or uvx is missing:

  1. Install uv from the official uv installation guide.

  2. Open a new terminal so your shell reloads its PATH.

  3. Verify the install:

    uv --version

  4. Start Faheem Code again:

    faheem-code

Browser does not open or shows A blank page​

Faheem Code listens on http://localhost:8000 by default.

If nothing opens automatically:

  1. Open http://localhost:8000 manually.

  2. Check the terminal running Faheem Code for startup errors.

  3. If port 8000 is busy, start on another port:

    faheem-code --port 3000

  4. Open http://localhost:3000.

If the browser page loads but stays blank, refresh once and check the terminal for frontend or backend startup errors.

Port already in use​

If startup says port 8000 is already in use, run Faheem Code on another port:

faheem-code --port 3000

If you are using Docker, map a different host port:

docker run -it --rm \
  -p 3000:8000 \
  -v ~/.faheem-code:/home/faheemcode/.faheem-code \
  -v ~/projects:/projects \
  ghcr.io/smart-national-solution/faheem-code-app:latest

Then open http://localhost:3000.

Docker daemon not running​

If Docker commands fail with a daemon or connection error:

  1. Start Docker Desktop on macOS or Windows, or start Docker Engine on Linux.

  2. Verify Docker is running:

    docker ps

  3. Run the Faheem Code Docker command again.

On Windows, use PowerShell command syntax from Install. PowerShell uses backticks (`) for line continuation instead of backslashes.

Backend is unreachable​

If Faheem Code loads but the active backend is disconnected:

  1. Open the backend switcher and select Manage Backends.
  2. Verify the backend host URL.
  3. Verify the API key if the backend requires one.
  4. Switch to the default local backend if available.
  5. Check the terminal or server logs for backend startup errors.

For the default local setup, you usually do not need to manually enter a backend API key. Faheem Code can generate and persist one locally.

For --public, VM, Modal, or other remote backends, use the LOCAL_BACKEND_API_KEY configured for that backend. Anyone with that key can access the backend, so keep it private.

Wrong backend URL or API key​

Backend URLs should point to the Faheem Code backend ingress, not to an unrelated local service.

Common examples:

SetupTypical URL
Default local Faheem Codehttp://localhost:8000
Local backend on another porthttp://localhost:8001
Docker mapped to host port 8000http://localhost:8000
VM or reverse proxyYour VM, proxy, or ngrok URL

If you changed the port with --port, use the port you selected.

Model or API key errors​

If a conversation fails before the agent responds, check Settings > LLM.

Common causes:

  • The API key is missing or expired.
  • The selected provider does not match the model name.
  • A custom or local model is missing the correct base URL.
  • A LiteLLM proxy token is invalid.
  • An OpenAI-compatible provider needs the provider, model, base URL, and key to line up.

Faheem Code classifies conversation errors and presents them with distinct banner variants:

  • Recoverable errors (such as authentication failures) are shown with a warning banner, indicating you can take action — for example, updating an API key or switching models.
  • Internal errors are shown with an error banner, indicating a problem that may require restarting the conversation or backend.

For model setup details, see:

LLM Provider NOT provided​

This error usually means the configured model name does not include enough provider information, or the provider field is not set.

Fix it by opening Settings > LLM and confirming:

  1. The LLM Provider field is set.
  2. The model ID matches that provider.
  3. Any custom Base URL is correct for the provider or local model server.
  4. The API key or token is valid.

If you are using Ollama, LM Studio, LiteLLM, or another OpenAI-compatible endpoint, use the provider and base URL expected by that service. See Local LLMs.

ACP agent credentials are not used​

ACP agents such as Claude Code, Codex, and Gemini CLI can be used in place of an LLM API key.

If an ACP agent does not authenticate:

  1. Confirm the provider CLI is signed in on the same machine where the backend runs.
  2. If the backend runs in Docker, on a VM, or in cloud infrastructure, do not assume it can see your laptop's CLI login.
  3. Add the required API key or secret for that backend.
  4. Reopen or restart the conversation after changing agent settings.

See ACP Agents for the credential rules.

Workspace is not where you expected​

The agent works in the workspace attached to the conversation.

If file changes appear in the wrong place or the agent cannot find your project:

  1. Use Open Workspace before starting the conversation.
  2. Confirm the conversation is using the backend you expect.
  3. For Docker, make sure the project is under the mounted projects directory, such as ~/projects, which appears as /projects inside the container.
  4. For a VM backend, remember that the agent sees files on the VM, not files on your laptop.
  5. For a cloud backend, use the cloud workspace or repository flow for that backend.

MCP settings are missing​

MCP configuration does not live under Settings.

Open the top-level Customize area, then go to MCP Servers.

If a configured MCP server is not available to the agent:

  1. Confirm it is saved on the active backend.
  2. Confirm any required secrets are saved under Settings > Secrets.
  3. Restart or start a new conversation if the server was added after the conversation began.

Automation features are unavailable​

Automations run on the active backend.

If the Automations view shows an unavailable or unhealthy state:

  1. Switch to the default local backend and check whether automations work there.
  2. Confirm the remote backend includes the automation service.
  3. Check the backend logs for automation startup errors.
  4. Confirm required MCP servers and secrets are configured on the same backend as the automation.

See Pre-built Automations.

LLM profiles do not match Faheem Code Cloud​

Faheem Code currently has fuller support for LLM profiles than the hosted Faheem Code Cloud UI.

If profiles appear in Faheem Code but not in Faheem Code Cloud directly, that can be expected while the Cloud rollout is still in progress.

Profiles and settings are also scoped to the active backend, so switching backends can change which profiles are available.

Update or uninstall is stuck​

Before updating or uninstalling, stop Faheem Code.

Stop the running process with Ctrl+C, then update or uninstall:

npm install -g @faheem-code/app@latest
npm uninstall -g @faheem-code/app

On Windows, if uninstall fails because uv.exe or another file is in use, close terminals running Faheem Code, stop related processes, and retry.

Uninstalling the package or image does not automatically delete persisted settings, secrets, or conversation history. Those live in the persistence directory you used, such as ~/.faheem-code.

Get help​

If you are still stuck: