> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose missing sessions, missing policies, failed delivery, and blocked agent actions.

<AccordionGroup>
  <Accordion title="No sessions appear in Cloud">
    <Tabs>
      <Tab title="Dashboard">
        Open **Administration → Keys** and confirm the machine key is active and has `events:add`. Then open **Observe → Events**, widen the time range, and clear environment and agent filters. If events exist, search the session ID and then check **Observe → Sessions** for grouping. If no events exist, diagnose the Failproof daemon from the CLI.

        <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/events-stream-current.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=e87ba86b877f602de73237d5a3565269" alt="The live Events stream with its primary filters visible and recent agent events arriving." width="2940" height="1618" data-path="images/dashboard/events-stream-current.png" />
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        failproofai config --status
        failproofai flush --wait --timeout 60
        fp list envs
        fp events --since 24h --limit 20
        fp sessions --since 24h --limit 20
        ```

        Confirm capture is enabled, the configured key has `events:add`, and the dashboard filter matches the emitted environment.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Python SDK events remain on disk">
    <Tabs>
      <Tab title="Dashboard">
        Clear filters in **Observe → Events** and search the exact SDK session ID. If nothing appears, inspect the SDK spool and Failproof daemon on the source machine.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        failproofai config --status
        failproofai flush --wait
        ```

        Confirm the agent process sets `AGENTEYE_SPOOL_TO_FAILPROOFAI=1` and that `$FAILPROOFAI_HOME/custom-agents`, otherwise `~/.failproofai/custom-agents`, exists before the SDK starts.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="The machine does not receive policies">
    <Tabs>
      <Tab title="Dashboard">
        Open **Admin → enforcement**, select the machine, and compare its assigned, reported, and previous versions. Confirm the deployment scope includes the machine and its key has `policies:pull`. Ingest can work even when policy delivery does not.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        failproofai config --status
        failproofai update
        failproofai config --status
        ```

        Confirm the machine ID and label match the dashboard target. Reconnect with a policy-capable key if the existing credential only grants event ingestion.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="An action is denied because the daemon is unavailable">
    <Tabs>
      <Tab title="Dashboard">
        Open **Admin → enforcement** and inspect the machine's last-seen time and reported version. If the machine is stale, treat this as a local daemon problem. Do not weaken the deployed policy solely to bypass an unavailable daemon.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        failproofai config --status
        failproofai update
        failproofai config
        failproofai config --status
        ```

        Restart or update `failproofaid`; rerun configuration when the CLI and daemon protocol versions differ. The configured daemon path fails closed by design.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="A custom policy does not load">
    <Tabs>
      <Tab title="Dashboard">
        For a Cloud-authored policy, open **Admin → policy editor**, select the draft, and review validation errors before publishing. For a local policy, use the CLI to validate it, then open **Observe → policy** after a test action to confirm decisions arrive.
      </Tab>

      <Tab title="CLI">
        Confirm the filename ends in `policies.js`, `policies.mjs`, or `policies.ts`, the module calls `customPolicies.add(...)`, and imports resolve from the policy file.

        ```bash theme={null}
        failproofai policies --install --custom ./checkout.policies.ts
        failproofai policies
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="An audit returns no findings">
    <Tabs>
      <Tab title="Dashboard">
        Open **Analyze → audits**, select the run, and check whether model analysis ran. Then compare its scope and window with **Observe → sessions** and open representative traces from that population.

        A zero result is meaningful only when analysis ran successfully. If analysis was skipped or failed, the run produces no findings and keeps the unanalysed window open for a future successful run. If model analysis is disabled, the audit also produces no findings because the deterministic credential and PII scan records statistics but no longer raises findings.

        <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/audit-new.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=5ff2eacb3773c1acd30535a8395e5603" alt="The audit form where environment, agent, cadence, and sweep window define the session population." width="1279" height="879" data-path="images/dashboard/audit-new.png" />
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        fp audits show <audit-name>
        fp audits runs <audit-name>
        fp sessions --since 24h --env production
        fp audits context-show <audit-name>
        fp audits run <audit-name>
        fp audits findings --audit <audit-name>
        ```

        If the run stayed queued, wait for audit-agent capacity or ask the deployment operator to inspect the audit fleet. A queued audit retries; it is not immediately skipped.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Online evaluations do not run automatically">
    <Tabs>
      <Tab title="Dashboard">
        Open a completed session and check whether a manual evaluation succeeds. Hosted Cloud currently has no evaluator endpoint control in the dashboard; the server operator must configure it.
      </Tab>

      <Tab title="CLI">
        Verify the evaluator itself, then inspect recent evaluation states:

        ```bash theme={null}
        curl https://evaluator.example.com/health
        fp evals --since 1h
        ```

        On self-hosted Cloud, confirm `EVALUATOR_ENDPOINT` is present on the server and `EVALUATOR_TOKEN` matches the evaluator. Automatic evaluation is disabled when the endpoint is absent.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Cloud CLI authentication targets the wrong organization">
    <Tabs>
      <Tab title="Dashboard">
        Use the organization switcher and confirm the expected slug and permissions before comparing results with the CLI.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        fp whoami
        fp orgs current
        fp orgs perms
        ```

        In API-key mode, specify `fp --org <slug> --api-key <key> ...` or set `AGENTEYE_ORG`. Saved human-session organization state is intentionally ignored for API-key requests.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="A policy blocks valid work">
    <Tabs>
      <Tab title="Dashboard">
        Open **Observe → policy**, preserve the decision and linked session, and identify the false-positive condition. Then open **Admin → enforcement** and roll the affected machines back to the prior version. Create a narrower version in **Policy editor**, test it on a small scope, and expand only after valid work succeeds.
      </Tab>

      <Tab title="CLI">
        Cloud deployment rollback is dashboard-only. A local session pause does not disable Cloud-managed policies. If the dashboard is unavailable, capture the machine and deployment state and restore dashboard access rather than repeatedly retrying the blocked action.

        ```bash theme={null}
        failproofai config --status
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

When contacting support, include the CLI version, harness, environment, relevant session or deployment ID, and the output of `failproofai config --status` with secrets removed.