Skip to main content
Version: v1

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.

Issue: Agent Cannot Find report.pdf (or Python FileNotFoundError)​

  • Symptom: You uploaded a file with a normal name, but the agent looks for a long ID, or a Python script cannot open report.pdf.
  • Solution:
    1. Confirm the file is on the Workspace page (not only attached in Chat).
    2. Ask: β€œSearch the workspace for report.pdf.”
    3. Ask the agent to open it by name. Current ActonOS mirrors workspace files under their original names for scripts (user-workspace/report.pdf).
    4. If the file was only dropped into Chat, ask: β€œSave this to the workspace as report.pdf.”

Issue: File β€œSent” on Zalo but Nothing Appears​

  • Symptom: The agent (or plugin log) says the file was sent. No file shows in the Zalo chat, and there is no obvious error.
  • Solution:
    1. Re-install the latest Zalo plugin (.actonpkg). Older plugins used Telegram-style multipart uploads, which Zalo ignores while still returning HTTP 200.
    2. Open Plugins β†’ Zalo β†’ Logs. A current plugin fails clearly when Zalo returns ok: false.
    3. Send to one specific Zalo conversation, not β€œall channels.”
    4. Confirm the bot can send files in that chat (pairing completed, bot not restricted).

Issue: Downloaded PDF Has Broken Fonts​

  • Symptom: Telegram or Discord received a PDF, but opening it shows missing or garbled fonts.
  • Solution: Re-install the latest channel plugin and send the file again from the Workspace. Older plugins put binary PDF bytes through a text JSON field, which replaces invalid UTF-8 and damages font tables. Current plugins send the raw file bytes.

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. Large compiles may hit this ceiling. Split the work or run it outside the sandboxed tool call.

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.