Skip to main content

Common Errors

This page collects recurring setup and runtime issues.

Submodule problems​

Symptom​

Build fails or shared imports cannot be resolved.

Checks​

  • run git submodule update --init --recursive
  • verify share-entity exists
  • verify expected branch is checked out in share-entity

Dependency install problems​

Symptom​

Project starts failing immediately after clone.

Checks​

  • confirm pnpm install was run in the correct repository
  • confirm Node.js version is compatible with the project
  • delete and reinstall dependencies if lockfile drift is suspected

Missing environment config​

Symptom​

Service starts but fails on DB, auth, or external connectivity.

Checks​

  • confirm .env or config files were provided
  • confirm required infra services are running
  • confirm credentials and hostnames are correct for local use

Frontend login issues​

Symptom​

Portal loads but login flow or callback fails.

Checks​

  • verify OIDC and SSO config values
  • verify frontend proxy or API base URLs
  • verify authentication service is running

What to add over time​

As issues are discovered, document:

  • exact error message
  • root cause
  • permanent fix
  • workaround if permanent fix is not immediate