Diagnostic Guide

Sovereign Diagnostics.

MeltyBase is a complex, high-performance infrastructure. While our autonomous systems handle most failures, this guide provides the technical steps required to resolve edge cases and deep-stack issues.

💡 Pro-Tip: Deploy a Diagnostic Agent

MeltyBase agents have native access to the AuditStore and HealthCheck APIs. If you encounter an issue, we highly recommend allowing an LLM Agent of your choice (via the Playground or OpenClaw) to assist. Simply paste the error logs into the agent context and ask it to propose a resolution based on the local system state.

01. Connectivity & Database

Database Connection Failure

Symptoms: FATAL: password authentication failed or connection refused.

Resolutions:

  • Verify DATABASE_URL in your .env file.
  • Check UFW firewall rules: ufw status. Ensure your application port (8081) is open.
  • Check Postgres logs: tail -f /var/log/postgresql/postgresql-15-main.log.
# Check database connectivity manually psql $DATABASE_URL -c "SELECT version();"

02. Auth & SSO

WebAuthn/MFA Failures

Symptoms: Credential not found or Insecure context.

Resolutions:

  • Ensure you are accessing the Studio over HTTPS. WebAuthn is disabled on insecure connections.
  • Verify that the RP_ID (Relying Party ID) matches your primary domain exactly.

SAML SSO Sync Issues

Symptoms: Infinite login loops or Invalid signature.

Resolutions:

  • Verify the Identity Provider (IdP) metadata URL is reachable from the MeltyBase Hub.
  • Check for clock skew between your server and the IdP: ntpdate -q pool.ntp.org.

03. Agent & AI Issues

Model Latency or Tool Failures

Symptoms: Agents timing out or failing to execute FORGE tools.

Resolutions:

  • Check your LLM provider's rate limits and quotas.
  • Verify that the agent has the necessary FORGE_WRITE or FILE_READ permissions in the project policy.
  • Check the **Sentinel PII Shield** logs to ensure legitimate data isn't being over-redacted, causing reasoning failures.

04. Storage & Sovereignty

S3/Minio "Access Denied"

Symptoms: Failed uploads or broken asset links.

Resolutions:

  • Verify your S3_ACCESS_KEY and S3_SECRET_KEY in the environment.
  • Check bucket policies to ensure the MeltyBase user has GetObject and PutObject permissions.
  • If using local storage, ensure the storage/ directory has 0755 permissions for the application user.

05. Real-time & Voice AI

WebSocket Timeouts

Symptoms: Voice interaction cuts off after 60 seconds.

Resolutions:

  • If using Nginx as a reverse proxy, increase proxy_read_timeout and proxy_send_timeout to 3600s.
  • Check for browser-side WebSocket disconnection in the console (Error 1006).

06. Migration & Sync

CDC (Change Data Capture) Lag

Symptoms: Multi-region projects not syncing in real-time.

Resolutions:

  • Check the Postgres replication slots: SELECT * FROM pg_replication_slots;.
  • Ensure the WAL level is set to logical in your postgresql.conf.
  • Verify network latency between Regional Portals and the Global Hub.

07. Infra & Performance

Process Restarts (PM2)

Symptoms: Intermittent 502 errors or service downtime.

Resolutions:

  • Check the PM2 process monitor: pm2 status.
  • Inspect error logs: pm2 logs melty-auth.
  • Check for Out-of-Memory (OOM) kills: dmesg | grep -i oom.

Audit Pulse Delays

Symptoms: Recent actions not appearing in the Audit export.

Resolutions:

  • Audit Pulse uses a 5-second batch buffer. Wait at least 10 seconds for events to be flushed to disk.
  • If delays persist, check the audit_logs table index health via Sentient SQL.

Final Resort: Global Logs

When all else fails, MeltyBase maintains a global diagnostic trace. You can access the unified log stream via the CLI:

# Stream all service logs melty logs --all --follow