Skip to main content

Troubleshooting

Common issues and solutions when developing Magic Apps.

Connection Issues​

"INFORMER_URL not set"​

The Vite plugin can't find your Informer server URL.

Fix: Create a .env file in your project root:

INFORMER_URL=http://localhost:3000
INFORMER_API_KEY=your-api-key

API calls return 401 Unauthorized​

Your credentials are invalid or missing.

Fix: Check your .env file has valid credentials:

  • API Key: Verify INFORMER_API_KEY is correct and the key hasn't been revoked
  • Basic Auth: Verify INFORMER_USER and INFORMER_PASS are correct

API calls return 403 Forbidden​

The app's informer.yaml doesn't include the API you're trying to call.

Fix: Add the resource to your informer.yaml:

access:
  datasets:
    - admin:your-dataset-id
note

In dev mode, the Vite proxy bypasses informer.yaml restrictions since it uses your admin credentials directly. A 403 in dev mode usually means the resource doesn't exist or your user lacks server-level access.

Workspace Issues​

"query() requires INFORMER_DEV_WORKSPACE"​

Your server handlers use query() but no dev workspace has been provisioned.

Fix: Run workspace init:

npm run workspace:init

Or add a migrations/ directory to your project — the Vite plugin auto-provisions the workspace on npm run dev.

"Workspace not found on server. Re-creating..."​

The workspace datasource was deleted from the server (e.g., by another admin).

Fix: This is handled automatically — the plugin re-creates the workspace. If it fails, run:

npm run workspace:init

Migration fails with "relation already exists"​

A migration is trying to create a table that already exists, usually because:

  • You modified an existing migration file instead of creating a new one
  • The workspace state is out of sync with the migration tracking table

Fix: Reset the workspace to start fresh:

npm run workspace:reset

Migration fails with SQL error​

Check the migration file for syntax errors. The error message from Postgres will tell you the exact line and issue.

Common causes:

  • Missing semicolons between statements
  • Using MySQL syntax in Postgres (e.g., AUTO_INCREMENT instead of SERIAL)
  • Referencing a table that hasn't been created yet (check migration file ordering)

Deploy Issues​

"Failed to create app"​

The deploy command couldn't create the app on the server.

Common causes:

  • 401/403 — Invalid credentials or insufficient permissions
  • Network error — Server is unreachable
  • Server doesn't support apps API — Very old Informer version

Fix: Verify your .env credentials and that the server is running.

Deploy succeeds but app shows old content​

The browser may be caching the old version.

Fix: Hard refresh the browser (Ctrl+Shift+R / Cmd+Shift+R) or clear the browser cache.

"Apps API not available, using legacy reports API"​

Your Informer server doesn't support the new /api/apps endpoint. The deploy command falls back to the legacy /api/reports endpoint automatically.

Fix: No action needed — the fallback works transparently. To use the new API, update your Informer server.

Server Route Issues​

Handler returns 404 "Method not found"​

The handler file exists but doesn't export a function for the HTTP method being used.

Fix: Export a named function matching the HTTP method:

// server/orders/index.js
export async function GET({ query }) {    // Handles GET requests
    return await query('SELECT * FROM orders');
}

export async function POST({ query, request }) {  // Handles POST requests
    // ...
}

Server route works in dev but not after deploy​

Common causes:

  • Missing server/ upload — Verify the server/ directory is in your project root (not inside src/)
  • Node.js APIs used — Server handlers run in a sandboxed V8 isolate in production. require(), fs, http, process, and other Node.js APIs are not available
  • External imports — Handlers can't import npm packages in production. All logic must be self-contained or use the provided query() and fetch() callbacks

Fix: Keep server handlers simple and self-contained. Use query() for database access and fetch() for API calls.

Theme Issues​

App doesn't respond to dark mode​

Your app may not be reading the theme context.

Fix: Read the theme from window.__INFORMER__:

const theme = window.__INFORMER__?.theme || 'light';
document.documentElement.setAttribute('data-theme', theme);

To test dark mode in dev:

// vite.config.js
informer({ mock: { theme: 'dark' } })

PDF Export Issues​

PDF is blank or missing content​

The headless browser may be capturing the page before your app finishes rendering.

Fix: Signal when your app is ready:

window.informerReady = false;

// After all content is rendered...
window.informerReady = true;

PDF has grey boxes where shadows should be​

Box shadows render poorly in PDFs.

Fix: Remove shadows in print mode:

@media print {
    * { box-shadow: none !important; }
}