Skip to main content

​
Troubleshooting

Something doesn’t feel right with your agents. This page helps you figure out what’s happening and get ACME’s diagnostic tools working for you.

​
Start Here: Generate a Diagnostic Bundle

Before reaching out to support, generate a diagnostic bundle. This gives you (and us) everything needed to understand your situation: 
acme support bundle
The bundle collects:
  • Recent reliability signals and detection history
  • Protection activity from Sentinel/Watchdog (if active)
  • Routing posture from SphinxGate (if configured)
  • Compaction and context indicators
  • OCTriage output for recent incidents
What it does NOT collect:
  • API keys or tokens
  • Secret values or credentials
  • Contents of openclaw.json or equivalent config files
The bundle is generated locally. Nothing is sent anywhere until you share it.

​
Common Situations

​
My agent looks healthy but isn’t making progress

This is a stall — one of the most common agent failure modes. The process is alive, but work isn’t advancing. Step 1: Run OCTriage 
acme triage --agent <your-agent-name>
OCTriage will classify the failure and give you a recommended next step. Step 2: Check if Sentinel is running 
acme sentinel status
If Sentinel isn’t running, it won’t have caught the stall. Start it with acme sentinel start for future protection. Step 3: Look for hung external calls A stalled agent is often waiting on a model API call that never returned. Check your agent’s logs for the last outgoing API call — if there’s no corresponding response, that’s your culprit.

​
My RadCheck score is worse than last time

A declining RadCheck score means new risk factors were detected or existing ones worsened. Run RadCheck with verbose output: 
acme radcheck --verbose
Compare the component breakdown to your previous scan. The specific component that declined tells you where to focus:
Component droppedWhat to investigate
Stall RiskNew retry patterns? Removed timeouts?
Silence GapsNew long-running operations? Changed heartbeat config?
CompactionContext usage increasing? Memory leaks?
HygieneConfig changes? New dependencies?

​
Sentinel is alerting but I don’t know what to do

Sentinel detected something — now what? Step 1: Check the alert context 
acme sentinel log --tail 20
The alert context tells you which agent, what pattern, and when. Step 2: Pull an Agent911 snapshot 
acme agent911 snapshot
Agent911 aggregates the Sentinel detection with other signals and gives you prioritized recommended actions. Step 3: Run OCTriage on the affected agent 
acme triage --agent <agent-name>
OCTriage classifies the specific failure and tells you the concrete next step.

​
OCTriage says “UNKNOWN” — pattern not recognized

This happens with unusual failure patterns. Here’s how to handle it:
  1. Generate a diagnostic bundle: acme support bundle
  2. Note any recent changes to your agent configuration
  3. Check if your agent framework version changed recently
  4. Contact support with the bundle attached — UNKNOWN patterns are something we want to learn from

​
Agent911 shows “UNKNOWN” status for an agent

This typically means Agent911 can’t see the agent — usually a Sentinel connectivity issue. Check Sentinel status: 
acme sentinel status
acme sentinel log --tail 10
If Sentinel isn’t connected, Agent911 has no visibility. Restart Sentinel if needed: acme sentinel restart

​
I can’t connect to the ACME CLI after install

Verify the install: 
which acme
acme --version
If acme isn’t found, the install didn’t complete or the binary isn’t in your PATH. Re-run the installer: 
curl -fsSL https://acmeagentsupply.com/install.sh | bash
After install, restart your terminal or run: 
source ~/.bashrc   # Linux
source ~/.zshrc    # macOS

​
Getting Help

If troubleshooting here doesn’t resolve your situation:

Live Chat

Chat with the support team on the support page. Have your diagnostic bundle ready.

Email Support

Send your diagnostic bundle to support@acmeagentsupply.com
When contacting support, include:
  1. Your diagnostic bundle (acme support bundle)
  2. Your ACME CLI version (acme --version)
  3. Your operating environment (macOS / Linux / Docker / k8s)
  4. What you were doing when the issue occurred
  5. What you expected vs. what happened
The more context you provide, the faster we can help.