Troubleshooting

Symptoms are grouped by where you notice them. Server messages are quoted as they appear in the logs (Winston, plain text on stdout).

The server does not start

Message	Cause	Fix
Provide a valid asset updater	ASSET_UPDATER is not dropbox or onedrive.	Set it. There is no “no sync” mode; a driver is mandatory.
Failed to read mailconfig.json then exit	MAILCONFIG is unset and server/mailconfig.json is missing or unreadable from the process working directory’s parent of dist/ (the server reads ../mailconfig.json relative to the compiled env.js).	Set MAILCONFIG to the base64 of your JSON, or keep mailconfig.json next to package.json.
failed to start asset updater then exit	The driver’s initialize() failed: for Dropbox, the refresh token could not be exchanged (Failed to refresh Dropbox token).	Check DROPBOX_APP_KEY, DROPBOX_APP_SECRET, DROPBOX_REFRESH_TOKEN. See Dropbox.
Connection refused on Postgres	DATABASE_URL unset and nothing listens on localhost:5432, or wrong credentials.	Start docker-compose up -d in server/, or set DATABASE_URL.
TypeError: Invalid URL at first S3 use	MAIN_S3_URL or ASSETS_S3_URL missing or not a URL.	Use the http://key:secret@host:port/bucket form.
Migration error at boot	Migrations run automatically and one failed, usually because the database was created by hand without the uuid-ossp extension or with a different schema.	Start from an empty database owned by the DATABASE_URL user. See Upgrading.

Sync does nothing

Symptom	Cause	Fix
Log says Dropbox listing is empty, skipping sync to avoid deleting all assets	The app sees an empty root: wrong permission type (app folder vs full Dropbox), wrong account, or the files live in the team space while DROPBOX_USE_TEAM_ROOT is false.	Re-check the app’s access type and set DROPBOX_USE_TEAM_ROOT=true for Dropbox Business team folders.
Folders appear but files stay in status creating with no thumbnail	The worker is not running, so asset/update-content jobs pile up.	Run one process with ENABLE_WORKER=true. See Worker and scaling.
Files appear but have no preview	A system package is missing: ffmpeg (video), ghostscript (PDF, EPS, AI), libreoffice (office documents), imagemagick.	Install them; the server/Dockerfile does. Then run npm run cli -- check-integrity to re-queue the files.
A file changed in Dropbox but Damvia still serves the old version	The sync does not compare checksums, so changed content is only caught by the daily integrity check, and only when the size differs.	Run the integrity check by hand. If the new file has exactly the same size, set the row to outdated in SQL: UPDATE asset_files SET status = 'outdated' WHERE name = '...'; and the worker re-fetches it.
OneDrive: nothing is listed, no error	ONEDRIVE_DRIVE does not point to an existing path, or the app registration lacks Files.Read.All application permission with admin consent.	See OneDrive.

Users cannot get in

Symptom	Cause	Fix
After sign-up the screen says the account must be approved	approved is false: the email domain is not in the authorized domains list.	An admin or a manager of the user’s region approves them under /admin/users, or add the domain under /admin/authorized-domains for future sign-ups. The very first admin is promoted in SQL: see First admin.
The verification or login email never arrives	SMTP settings are wrong, or the worker is off (all emails are queued jobs).	Check SMTP_*, check the worker is enabled, look at the mailer/* queues in pgboss.job. In development, open MailHog at http://localhost:8025.
The approval request reaches nobody	email/request-approval only mails admins and managers of the requester’s region. If that region has none, the job sends nothing.	Give each region at least one manager or admin.
Everyone was logged out at once	APP_SECRET changed.	Expected: tokens are signed with it.
A guest’s invitation link says the link expired or shows the login page	The invitation’s expiresAt has passed, or the token in ?dam_token= was issued before an APP_SECRET change.	Re-invite the guest.

Downloads

Symptom	Cause	Fix
“Email” downloads stay in preparing	Worker off, or download/create-archive failing (check the job log).	Enable the worker; check disk space in the server’s temp directory, the archive is built there before upload.
Download link opens /link-expired	The download is older than 7 days, or the id is unknown.	Create a new download.
The browser cannot reach the presigned URL	The S3 endpoint in ASSETS_S3_URL is only resolvable from the server.	Expose the S3 endpoint publicly (HTTPS) and use that hostname in the URL. See Object storage.
You cannot download more than 10GB.	The selection’s total original size is at or above 10 GB.	Split the download.

Client

Symptom	Cause	Fix
Every request fails with a network error	VITE_API_ENDPOINT points to the wrong host, or was changed without rebuilding.	Fix client/.env and rebuild; the value is baked in at build time.
Deep links (for example /collections/abc) return 404 from the web server	The static host lacks the SPA history fallback.	See Client build.
The brand colour did not change	Tailwind reads client/.env at build time.	Restart npm run dev or rebuild.