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

> Troubleshoot Macro Inc. issues by verifying Doppler configuration, applying database migrations, enabling debug logging, and resetting your local stack for seamless service syncing.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
cargo sqlx prepare

```

The `macro_db_client` crate README lists these helper commands.

### Force Reset Corrupted Migrations

When migrations become unrecoverable, [`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/CLAUDE.md) recommends this nuclear option:

```bash
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**:

```bash
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`](https://github.com/macro-inc/macro/blob/main/apps/web/AGENTS.md) provides this macOS command:

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

```

### Check Container Logs

When running via Docker Compose:

```bash
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

```bash

# 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

```bash
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:

```rust
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**:

```bash
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:

```bash
#!/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`](https://github.com/macro-inc/macro/blob/main/README.md) | Architecture overview and local run instructions |
| [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | Complete stack startup guide |
| [`services/document_cognition_service/README.md`](https://github.com/macro-inc/macro/blob/main/services/document_cognition_service/README.md) | Service-specific environment and DB commands |
| [`crates/macro_db_client/README.md`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/README.md) | Database helper scripts |
| [`apps/web/AGENTS.md`](https://github.com/macro-inc/macro/blob/main/apps/web/AGENTS.md) | Host process logging commands |
| [`apps/web/docs/playwright-debugging.md`](https://github.com/macro-inc/macro/blob/main/apps/web/docs/playwright-debugging.md) | UI test debugging |
| [`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.