Macro Inc. Troubleshooting: Common Issues and Fixes for the Macro Platform

The most common troubleshooting steps for Macro Inc. involve verifying environment configuration with Doppler, applying database migrations, enabling debug logging, and resetting the local development stack when services fail to sync.

Macro is a modular, hexagonal Rust/SolidJS workspace developed by Macro Inc. that bundles email, chat, docs, tasks, agents, and CRM into a single system. If you're running into issues with this interconnected service architecture, this guide covers the Macro Inc. troubleshooting steps derived directly from the source code to resolve failures quickly.

---

Verify Environment Configuration

Environment-variable misconfiguration is the leading cause of startup failures in Macro services.

Check Doppler Project and Config

Each service requires its own Doppler project. The document_cognition_service README specifies this command structure:

doppler run --command="just debug" -p <service> -c <YOUR_CONFIG>

Replace <service> with the crate name (e.g., document_cognition_service) and <YOUR_CONFIG> with your created configuration.

Update .env From Sample

When .env files drift out of date:

cp .env.sample .env

# Edit .env with required keys, then restart the service

Ensure DATABASE_URL Is Set

SQLx compilation fails without this variable. Export it manually or verify Doppler provides it:

export DATABASE_URL=postgres://...

The cargo sqlx prepare step will fail otherwise, as noted in the Document Cognition Service README.

---

Apply Database Migrations

Schema drift causes runtime column does not exist errors and SQLx cache misses. Macro Inc. troubleshooting requires consistent database state across multiple PostgreSQL databases.

Initialize Required Databases

From the repository root, run the appropriate setup command for your service:

just setup_macrodb      # Main MacroDB

just setup_commsdb      # Communications database

just setup_emaildb      # Email database

just setup_contactsdb   # Contacts database

Refresh SQLx Query Cache

After any schema change:

cargo sqlx prepare

The macro_db_client crate README lists these helper commands.

Force Reset Corrupted Migrations

When migrations become unrecoverable, CLAUDE.md recommends this nuclear option:

just force_drop_db      # Reset the database

just setup_macrodb      # Re-apply migrations

---

Enable Debug Logging

Services respect the RUST_LOG environment variable. Enable verbose output for Macro Inc. troubleshooting:

RUST_LOG=document_cognition_service=debug,info \
  doppler run --command="just debug" \
  -p document_cognition_service \
  -c my-config

Stream Logs From Host Process

For system-level debugging, apps/web/AGENTS.md provides this macOS command:

/usr/bin/log stream \
  --predicate 'process == "macro"' \
  --info --debug --style compact

Check Container Logs

When running via Docker Compose:

docker compose logs <service>

---

Reset the Local Development Stack

Persistent state issues often require a clean slate. The "Running it locally" section in the top-level README documents this workflow.

Full Stack Reset Procedure

# Stop all containers

docker compose down

# Force-drop and recreate databases

just crates/macro_db_client/drop_db -y -f
just setup_macrodb

# Restart supporting infrastructure

just run_dbs  # Starts Postgres, Redis, OpenSearch

# Relaunch your service

doppler run --command="just debug" \
  -p document_cognition_service \
  -c my-config

---

Verify Service Connectivity

Macro services expose Swagger UI endpoints for health verification.

Quick HTTP Health Check

curl -I http://localhost:8084/api-doc/openapi.json

A 200 OK response confirms the Document Cognition Service is operational. Adjust the port for other services.

Rust Health-Check Implementation

From the codebase patterns, implement programmatic checks:

use reqwest::StatusCode;

pub async fn health_check(url: &str) -> Result<(), anyhow::Error> {
    let resp = reqwest::get(url).await?;
    if resp.status() == StatusCode::OK {
        Ok(())
    } else {
        anyhow::bail!("Service unhealthy: {} returned {}", url, resp.status())
    }
}

---

Debug UI Issues With Playwright

For @mentions synchronization problems or SolidJS state issues, the Playwright debugging guide covers UI-level Macro Inc. troubleshooting:

just test_web  # Runs the full Playwright suite

Add console.trace statements in components to surface state changes during test execution.

---

Complete Local Startup Script

This script automates the full reset-and-restart workflow:

#!/usr/bin/env bash
set -euo pipefail

# Reset database state

just crates/macro_db_client/drop_db -y -f
just setup_macrodb

# Launch infrastructure containers

just run_dbs

# Start Document Cognition Service with debug output

doppler run --command="just debug" \
  -p document_cognition_service \
  -c my-local-config

# In another terminal: start web client

cd apps/web && bun run local-dcs

---

Key Source Files Reference

Path	Purpose
README.md	Architecture overview and local run instructions
docs/RUNNING_LOCALLY.md	Complete stack startup guide
services/document_cognition_service/README.md	Service-specific environment and DB commands
crates/macro_db_client/README.md	Database helper scripts
apps/web/AGENTS.md	Host process logging commands
apps/web/docs/playwright-debugging.md	UI test debugging
CLAUDE.md	General troubleshooting and migration guidance

---

Summary

• Environment configuration: Use doppler run with correct -p and -c flags; keep .env synced with .env.sample
• Database state: Run just setup_macrodb (and variants); execute cargo sqlx prepare after schema changes
• Debug visibility: Set RUST_LOG=service_name=debug,info; use /usr/bin/log stream for system logs
• Nuclear option: docker compose down, just force_drop_db, just setup_macrodb, restart services
• Health verification: curl -I http://localhost:<port>/api-doc/openapi.json
• UI debugging: just test_web with Playwright and console.trace instrumentation

---

Frequently Asked Questions

Why does my Macro service fail with "no cached data" SQLx errors?

This indicates stale or missing query metadata. Run cargo sqlx prepare from the service directory to refresh the offline query cache. Ensure DATABASE_URL is exported and accessible. If the error persists, verify the database exists with just setup_macrodb.

How do I completely reset my local Macro development environment?

Execute the full reset sequence: docker compose down to stop containers, just crates/macro_db_client/drop_db -y -f to force-drop databases, just setup_macrodb to re-initialize, then just run_dbs to restart infrastructure before relaunching your service with Doppler.

Which Doppler project name should I use for a specific service?

Use the crate name as the project name. For the Document Cognition Service, run doppler run --command="just debug" -p document_cognition_service -c <your-config>. Check services/<service_name>/README.md for service-specific requirements.

Where can I find Macro service logs when running outside Docker?

Use the macOS log stream command from apps/web/AGENTS.md: /usr/bin/log stream --predicate 'process == "macro"' --info --debug --style compact. This captures output from native host processes including Rust services launched directly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}