Skip to main content
Version: v0.2 (Next)

Troubleshooting & Problem Resolution

A comprehensive guide to diagnosing and resolving common operational issues across Bare-Metal, Docker, WASM Plugins, and AI Agent workflows in ActonOS.

1. Installation & Network Issues​

Issue: Port 8080 Already in Use (Docker)​

  • Symptom: docker: Error response from daemon: Bind for 0.0.0.0:8080 failed: port is already allocated.
  • Solution: Map ActonOS to an alternate host port: 
    docker run -d -p 8888:8080 -v acton-data:/data ghcr.io/actonos/actonos:latest
    Then access the dashboard at http://localhost:8888.

Issue: Captive Portal Does Not Auto-Open on Wi-Fi Connect (Bare-Metal)​

  • Symptom: Connected to ActonOS-XXXX but no browser popup appears.
  • Solution: Open any browser window and manually navigate to http://192.168.4.1 or http://acton.local:8080. Ensure mobile data / cellular connection is temporarily disabled.

2. WASM Plugins & Extension Runtime​

Issue: domain not permitted in manifest net_outbound​

  • Symptom: Plugin fails to perform HTTP request; log reports egress security violation.
  • Solution: Open manifest.json for the plugin and ensure the target domain hostname (e.g. "api.weather.com") is explicitly declared inside permissions.net_outbound. Re-package and upload the .actonpkg.

Issue: missing secret ... in vault​

  • Symptom: Plugin fails to authenticate or retrieve credentials during startup.
  • Solution: Check that the required secret key prefix is declared in permissions.secrets and configured in the plugin's Settings modal in the ActonOS Web UI.

Issue: WebSocket connection closed (-1)​

  • Symptom: Chat channel fails to receive live inbound frames.
  • Solution: Check if the remote service requires authentication headers or custom token handshakes during connection establishment (acton_ws: ws_connect).

3. Channels & Integrations​

Issue: Telegram Bot Does Not Respond​

  • Symptom: Bot receives messages but does not reply.
  • Solution:
    1. Check Plugins in the dashboard to confirm the Telegram plugin status is 🟒 Running.
    2. Verify you completed the Pairing PIN verification step.
    3. Ensure your Telegram Bot Token was not revoked via @BotFather.

Issue: Discord Bot Missing Message Content Intent​

  • Symptom: Bot joins server but cannot read user prompts.
  • Solution: In the Discord Developer Portal, navigate to Bot β†’ Privileged Gateway Intents and enable Message Content Intent.

4. Execution Sandbox & Approvals​

Issue: Agent Tool Fails with Out of Memory (OOM)​

  • Symptom: Command terminates with exit code 137.
  • Solution: The default Bubblewrap sandbox limits processes to 512 MB RAM. If compiling large codebases, adjust the agent's memory ceiling in agent_manifests.json under sandbox_memory_mb: 1024.

Issue: Mission Paused on Pending Approval​

  • Symptom: Mission shows Running but progress does not advance.
  • Solution: Check the top Pending Approvals Banner on the Dashboard or navigate to Missions β†’ Approval Queue to approve or reject the paused mutation.