MemnoxDocs
Open console

ReferenceHelpTroubleshooting

Troubleshooting

Grouped by symptom, because that is what you have when you arrive.

My editor is not being governed

  1. 1

    Did you restart the editor?

    Hooks are read at startup. This is the cause more often than everything else combined.

  2. 2

    Is the runtime up?

    bash
    memnox status

    A hook that cannot reach the runtime fails open, a dead process never blocks development, so governance stops silently.

  3. 3

    Is there a credential?

    memnox status reports it. A hook with no credential allows everything, which looks exactly like being protected.

    A GUI-launched editor inherits no shell environment, so an exported MEMNOX_AGENT_TOKEN never reaches it. That is why setup writes ~/.memnox/config.json.

  4. 4

    Is anything actually enforced?

    The first run observes. memnox status shows "Observed: N would have been stopped if enforcing", if that number is rising, it is working and not yet enforcing.

A rule is blocking legitimate work

bash
memnox explain <eventId>

Names the exact rule and its reason. Then narrow the match by adding a target, a working directory or a branch, and open a pull request against the policy file.

An omitted match field matches everything, which is the usual cause of a rule firing wider than intended.

For right now:

bash
memnox approvals override <id> --reason "…"     # audited as critical

A rule is not firing when it should

Check

Is a more permissive rule also matching?

No, most restrictive wins. Order does not matter

Is it in mode: monitor?

Then it records and does not apply

Is the environment right?

An environments: list that does not include the one in play never matches

Is it an argument match?

Those need an enforcement point that sees arguments, the firewall or the hook, not a bare SDK call

Is the default effect allow?

Then anything unmatched proceeds

Nothing is arriving from a connector

  1. 1

    Is a trigger subscribed?

    A connection is not a subscription. This is the first thing to check.

  2. 2

    Is the permalink base URL set?

    Slack and Jira do not send links. Without slack.workspaceUrl or jira.baseUrl, those events are rejected at the normalizer, every source event carries a resolvable URL, with no exceptions.

    From outside this looks identical to nothing arriving.

  3. 3

    Is the connection enabled?

    A paused connection looks like a broken one from Activity.

  4. 4

    Anything under failed deliveries?

    Connectors → the connection → Failed deliveries. A delivery that arrived and then failed downstream shows here rather than in the provider's own log.

  5. 5

    Has the grant expired?

    Reconnect. The integration provider owns refresh, so an expired grant is fixed there, and a grant dies with the account of whoever consented.

Everything is showing as untrusted

Author trust is a lookup against the people known in that workspace. An unrecognised author is tainted, fail-closed.

Extraction answers 503

No model credential. Extraction is BYOK, set ANTHROPIC_API_KEY (or your configured provider's key). Everything else in the product works without it.

Suggestions are about the wrong things

Symptom

Suggestions about other companies' products

The onboarding profile is empty

Suggestions from a stranger's opinion

The author never resolved to a person

The same suggestion repeatedly

Rejected, but the thread keeps being re-ingested

Nothing worth approving

Too many low-signal triggers subscribed

Approvals are piling up

Rising latency means the rule is routed to people who are not looking. That is an audience problem, not a rule problem, and if it is not fixed, somebody will eventually delete the rule instead.

For overnight automation, scope the rule with a time window rather than leaving a pipeline waiting for somebody asleep.

Webhooks are failing

Symptom

401 in the provider's delivery log

Wrong secret, or the body is being re-serialized before verification

Worked yesterday, no config change

Clock skew. The replay window rejects a stale timestamp

Accepted, then nothing appears

Rejected at the normalizer, check the permalink base URL

Bursts dropped

Per-workspace webhook rate limit

Verify over raw bytes, before parsing, with a constant-time comparison.

Startup fails with Redis configured

Deliberate. If MEMNOX_REDIS_URL is set and Redis is unreachable, startup fails rather than silently degrading, otherwise N pods would each enforce the full rate limit and nothing would say so.

pgvector unavailable

Expected on stock Postgres. Semantic search falls back to a scan. Swap the image for a pgvector build to index.

Sign-in fails behind a load balancer

Sign-in state is per-process: the OAuth callback must reach the instance that started the flow, or it fails closed. Use sticky sessions on the auth routes.

The audit chain reports BROKEN

bash
memnox audit verify
# Audit chain BROKEN at event #91 (0f3a…): content-mismatch

Something edited or deleted a row. This is tamper evidence working as designed, so treat it as a finding rather than a bug: investigate who has database access, and configure a sink so the next copy lands outside this trust boundary.

Still stuck

bash
memnox status
memnox audit | tail -20
memnox explain <eventId>
memnox replay <sessionId>

Those four, in that order, answer most questions about a specific action.

Configuration

Every setting, and the precedence between them.

Glossary

Every term this documentation uses.