Skip to main content

Common Issues

This page summarizes several technical issues you may encounter and practical solutions to resolve them.

1. Data Sync Failure (Offline Sync)​

Symptoms: Recently changed data does not appear when opened on another device or after the app is restarted. Solutions:

  • Ensure the app stays open for a while after an internet connection is detected to allow synchronization time.
  • Check the Network tab in the browser (Developer Tools) to ensure there are no 403 or 401 errors when the app attempts to push data to Supabase.
  • If synchronization still fails, refresh the page (make sure the data is saved in your browser's local storage).

2. Database Connection Failure (GitHub Actions)​

Symptoms: Error psql: error: could not connect to server: Connection timed out during automatic backup. Solutions:

  • Make sure you are using the Transaction Pooler (Port 6543) and not the direct connection (5432).
  • Check if SUPABASE_DB_URL in GitHub Secrets is correct and uses the proper URI format.

3. Images Not Appearing (Cloudflare R2)​

Symptoms: Images in Notes or Drawings are broken or not displayed. Solutions:

  • Ensure the API Token in Cloudflare has "Edit" or "Admin" permission for the bucket.
  • Check if R2_ACCOUNT_ID and R2_BUCKET_NAME in the .env file are correct.
  • Ensure CORS in the Cloudflare R2 dashboard is allowed for your app's official domain.

4. AI Not Responding Issue​

Symptoms: Chat AI stops in the middle or displays a connection error message. Solutions:

  • Check the API Key in Settings > AI Configuration. Make sure the key is still active and has sufficient quota.
  • If using Custom/OpenAI Compatible, make sure the Base URL is correct and includes /v1 at the end (e.g., http://localhost:20128/v1).
  • Check the terminal logs (if running locally) or the Network tab in the browser for error details from the API provider.

5. SQL Parsing Error​

Symptoms: The entered SQL does not convert to a diagram or an error occurs during parsing. Solutions:

  • Make sure the SQL syntax uses the PostgreSQL dialect (the main supported dialect).
  • Check for unsupported special characters or overly complex syntax. Try parsing table by table if the SQL file is too large.

6. Docker Issue (Deployment)​

Symptoms: Docker container is not accessible on port 3000. Solutions:

  • Make sure port 3000 is not already in use by another application on the host machine.
  • Check container logs with the docker logs erd-app command for startup error messages.
  • Ensure the .env file is included when running the container (--env-file .env).

8. 403 Forbidden Error When Managing Model Catalog​

Symptoms: A 403 Forbidden error appears when creating or editing data in Settings > Model Catalog.

Cause: Your Supabase account is missing the is_super_admin flag in user metadata. The application checks this flag to grant access to the Model Catalog feature.

Solution:

  1. Open your Supabase Dashboard.
  2. Navigate to SQL Editor.
  3. Create a new query and run the following command, adjusting the email to match your admin account:
UPDATE auth.users
    SET raw_app_meta_data = raw_app_meta_data || '{"is_super_admin": true}'::jsonb
    WHERE email = 'admin@example.com';

Replace admin@example.com with your actual admin account email.

  1. After running the query, logout and login again to the ERD Builder Pro application.

Note: This issue is specific to Supabase (PostgreSQL) mode. Local PostgreSQL has a local super admin created through initial setup; Desktop/CLI use local automatic access.

9. Forgot Password in Self-Hosted Mode (Local PostgreSQL / Docker)​

Symptoms: Cannot log in to a self-hosted ERD Builder Pro deployment using Local PostgreSQL or Docker mode.

Cause: Self-hosted mode uses local authentication, not Supabase. There is no "Forgot Password" feature in the UI.

Solution:

  1. Open a terminal in the server or ERD Builder Pro project directory.
  2. Run the following command, replacing the email and password:
npm run reset-password -- --email your-admin-email@example.com --password newpassword123
  1. The script will find the user, hash the password, and update the database.
  2. No application restart required — the user can log in immediately with the new password.

Note: Replace the email with the actual super-admin email. This solution is specific to Local PostgreSQL and Docker modes. Supabase mode uses the Supabase dashboard for password reset. Desktop/CLI use local auto-login and do not use the web login form.

10. Repeated Super-Admin Registration or Invalid Credentials​

Symptoms: After logout, the application returns to Create administrator account, or logging in with admin@local.dev / admin123 shows Invalid credentials.

Cause: admin@local.dev / admin123 is the Desktop/CLI bootstrap credential and is deliberately rejected in Local PostgreSQL self-host mode. Self-host seeding does not create default credentials; the super admin must be created through the initial setup screen.

Solutions:

  • Create an account with a new email and password through Create administrator account.
  • Ensure the server and seed command use DB_VARIANT=pg and the same DATABASE_URL.
  • Keep the same ERD_ENCRYPTION_KEY across restarts and deployments.
  • If the UI does not match the database, verify that the application is not using a different database or stale backend build.

11. AI API Key or DB Connect Password Cannot Be Used​

Symptoms: DB Connect requests fail after deployment, or AI reports that a stored API key cannot be decrypted.

Cause: ERD_ENCRYPTION_KEY is missing or changed. This key encrypts database connection passwords and AI API keys.

Solutions:

  • Restore the same ERD_ENCRYPTION_KEY from your secret manager or .env backup.
  • For Desktop/CLI, keep .erd-encryption-key beside the database, or set ERD_ENCRYPTION_KEY_FILE.
  • After restoring the key, save the affected credentials again if needed.

12. Canvas Feels Heavy/Laggy After Generate​

Symptoms: After you click the action button below the AI response in the Chat Panel (such as Replace All, Append, Create or Update ERD from SQL, or Create or Update Flowchart) for the first time, moving tables or symbols on the canvas feels heavy or "janky".

Cause: This is a technical limitation with the initial canvas state synchronization when receiving a large amount of new data from AI.

Solutions:

  • Simply Reload/Refresh your browser page once. After refreshing, the canvas will return to being smooth and normal.