For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/troubleshooting.md.
SFMC
  • English

      • Troubleshooting & Diagnostics

      When encountering server startup issues, inactive modules, or network errors, use the interactive troubleshooting wizard below for guided diagnosis. The complete checklist is also available below for search and fast reference.

      Self-check (monorepo)

      1. Run platform integration verify at repo root to validate packages and dependencies:
        pnpm run verify

      Comprehensive Troubleshooting Checklist

      1. Port Conflicts & Networking (Port Conflicts)

      Conflicted PortService InvolvedTypical Error / SymptomFix & Workaround
      19132 (UDP)BDS Core ProcessBDS fails to boot, crashes, or fails to bind portCheck for orphaned bedrock_server processes in the background; kill the PID via Task Manager / netstat.
      3001 (TCP)db-server Data DaemonLog outputs EADDRINUSE :::3001Update db_port in configs/db_config.json, or override via DB_PORT=3011 environment variable.
      3002 (TCP)qq-bridge (LLBot WS)LLBot connection rejectedVerify firewall rules allow the port, and ensure no duplicate bridge instances are running.
      # Windows inspect listening PID
netstat -ano | findstr 19132

# Linux / macOS inspect listening port
lsof -i :3001

      2. Database Daemon (db-server) Issues

      SymptomRoot CauseAction Steps
      Exits immediately, Cannot find module 'node:sqlite'Node.js version is too oldUpgrade Node.js to 22.13.0 or higher (the platform requires built-in SQLite support).
      Write failures or SQLITE_CORRUPTDisk errors or unclean power lossStop all services and restore the latest .sqlite database from <SFMC_ROOT>/data/backups/.
      SAPI requests to data service return 401 UnauthorizedModule token expired or invalidEnsure SAPI's ConfigManager.init() successfully fetched snapshot configs, then run mod reload.
      # Test local db-server daemon health
curl http://127.0.0.1:3001/api/health

      3. BDS Boot & Behavior Pack Assembly Gate

      1. Inspect Load Summary: Review terminal load output and individual log files under <SFMC_ROOT>/.sfmc/logs/.
      2. Test Pack Bundling: Execute sfmc> mod build to verify esbuild produces JavaScript bundles without TypeScript syntax errors.
      3. Check Add-on Conflicts: Check worlds/<level>/behavior_packs/ for duplicate or conflicting packs (see Add-ons Guide).

      4. Module Enabled in Lock but Inactive In-Game

      • Update Boundaries:
        • If you edited TypeScript code in sapi/src/: Run sfmc> mod reload to hot reload.
        • If you edited configs/*.json or manifest.json: You must restart BDS.
      • Lock Status: Confirm that enabled: true is set for this module in <SFMC_ROOT>/modules/module-lock.json.
      • Lifecycle Ordering: If entity/dimension operations fail during module boot, verify if ModuleRegistry.register should specify afterWorldLoad: true.
      • Dependencies: Check that all modules listed under dependencies in manifest.json are installed and enabled.

      5. QQ Bridge & Bot Connection Issues

      Official OpenAPI Backend (official)
      LLBot / OneBot Backend (llbot)
      1. Credentials: Check official.app_id and official.app_secret in configs/qq_config.json.
      2. IP Allowlist: In the QQ Open Platform developer console, ensure your server's public IP is added to the IP allowlist.
      3. Event Subscription: Ensure GROUP_AT_MESSAGE_CREATE is subscribed (messages in groups must @ the bot).
      4. Group OpenID: Copy the generated official.group_openid from initial trigger logs into configs/qq_config.json, then restart services.

      6. Hot Reload & Watch Troubleshooting

      SymptomDetails & Solution
      Changes in sapi/src don't take effect in-gameVerify that VS Code extension SFMC: Start Watch is active, or manually execute sfmc mod reload in the console.
      Reload succeeds but new commands don't respondCheck if command permissions were declared in registerPermissions; modifying manifest.json permissions or platform configs requires a BDS restart.

      7. Reporting Issues & Help

      If the issue persists after following these steps, please open an issue at GitHub Issues and include:

      • Complete terminal log output (or .sfmc/logs/ archive)
      • pnpm run verify output
      • node -v and Operating System details