Troubleshooting

Start here: gjalla status

Almost every problem is one of: not authenticated, not linked to a project, harness not installed, or stale local context. Run this first:

gjalla status

Every row should be green. Yellow or red rows tell you exactly which step is missing. The remaining sections cover the most common failure modes.

CLI / setup

”Command not found: gjalla”

Install with pipx install gjalla (preferred) or pip install gjalla. If pipx says the install succeeded but the command isn’t found, run pipx ensurepath and restart your shell.

API key not saving

The API key lives in ~/.gjalla/config.yaml. If gjalla status says “API Key: Not Configured” after running setup, check that the directory is writable and you’re not setting GJALLA_API_KEY in your shell to a stale value (env vars override the config file).

”Project not linked”

Run gjalla setup project <pid> to link explicitly, or re-run gjalla setup and pick the project from the list. The project ID is in the URL when you have the project open in the workspace.

Git hooks not running

Commits go through without an attestation check

The most common cause: another tool (husky, simple-git-hooks, pre-commit.org) is managing hooks and overwrote gjalla’s. Run:

gjalla setup --no-hooks

That writes the standalone scripts but doesn’t install hooks. Wire them into your hook manager:

# pre-commit
bash scripts/gjalla-attestation-check.sh

# post-commit
bash scripts/gjalla-post-commit-upload.sh

Commit says the attestation is stale

Your agent prepared the commit record, then staged files changed before the commit landed. Re-stage everything, run gjalla rules check, ask the agent to refresh the commit record, and commit again.

Need to bypass for a one-off commit

Human developers can skip the attestation check with SKIP_ATTESTATION=1 git commit .... Use sparingly; the whole point is the audit trail.

MCP / agent integration

Agent doesn’t see gjalla MCP tools

1. Run gjalla setup mcp: it auto-detects your editor and writes the right config file.
2. Restart your editor / agent. Most clients only load MCP servers at startup.
3. Check the MCP config file (.mcp.json, .cursor/mcp.json, etc.) was actually created and points to gjalla mcp serve.
4. If you don’t have gjalla[mcp] installed locally, the config falls back to uvx. Make sure uvx is on your PATH.

Agent ignores gjalla guidance

gjalla installs into each agent’s native guidance surface. If an agent is not following project rules or process:

• Run gjalla setup from the repo root to refresh installed guidance, hooks, MCP, and skills.
• Some agents only read guidance at session start. Restart the session.
• Run gjalla sync if you recently changed rules, skills, or memory in the web app.

Workspace / analysis

Overview is empty after analysis finishes

gjalla’s discovery runs on the default branch. Common causes:

• Repo is very small: small repos sometimes produce zero capabilities until you add code worth analyzing.
• Default branch is a vendor folder or a docs-only branch: change the analysis branch in Configuration.
• The analysis state is degraded. Look for the red banner at the top of the workspace and click “Re-run from settings."

"Analysis incomplete” banner won’t go away

Open Configuration and re-run analysis. If it consistently fails, check that the gjalla GitHub App still has access to the repo (it gets revoked sometimes when admins rotate permissions).

PR check runs aren’t appearing

• Confirm the GitHub App is installed on the repo and your branch matches the configured target.
• Check Automations → Change Review: if it’s set to Off, no checks will post.
• If only some checks appear, the missing evaluators are likely tier-locked or have Enabled turned off. Open Automations to confirm.

Sync / context freshness

Rules, skills, or memories aren’t updating

gjalla sync pulls the latest harness from the platform and installs it into supported agents. Run it after changing anything in Guardrails, then restart agents that only load guidance at session start.

Stale rules cache

The CLI caches rules locally for fast lookup. Run gjalla sync to refresh. gjalla rules show always reads from cache, so if you just changed a rule in the web app, sync first.

”Could not refresh context” during sync

If gjalla sync reports Could not refresh context (e.g. fetch_context failed), re-run with debug logging to see the underlying cause. GJALLA_DEBUG is an environment variable, not a CLI flag. Set it before the command (don’t pass it as --GJALLA_DEBUG or gjalla sync GJALLA_DEBUG=1):

GJALLA_DEBUG=1 gjalla sync

# Windows PowerShell:
$env:GJALLA_DEBUG=1; gjalla sync

This writes a full traceback to .gjalla/.platform/logs/sync.log. A 403/404 means an API-key access problem. Re-run gjalla auth login to get a fresh user-scoped key that inherits your team’s project access. A network error points to connectivity or a misconfigured API URL rather than access.

Working offline or away from your allowlisted network

gjalla commands that talk to the platform (sync, uploads) will queue or time out, but everything local still works: rules, gates, ledger, loops. Your queued attestations upload on the next successful gjalla sync.

GitHub App

Can’t install the GitHub App

If your org requires admin approval for app installations, gjalla tracks the pending request and activates automatically once an admin approves. No retry needed on your end: it’ll show up in the workspace when it’s active.

App installed but checks aren’t posting

The app needs Pull requests: read & write and Checks: write. If permissions were modified on the GitHub side, re-grant from the org’s GitHub Apps page.

Memories (alpha)

Memories from one agent aren’t reaching another

With the shared gjalla memory store, not only are all agents able to learn from each other, but your memory store is centralized, meaning it can be curated, scrubbed, and managed so that all agents will consistently operate with the same knowledge.

Still stuck?

Email support@gjalla.io with:

• Output of gjalla status
• What you were trying to do
• What happened instead
• Whether this is local-only or connected mode, and which agent you’re using

We read every email. Most issues are resolved within a day.