1 Troubleshooting

Nico edited this page 2026-05-26 00:31:28 -07:00

Table of Contents

• Troubleshooting
• I Cannot Log In
• I Am Logged Out Unexpectedly
• I Have No Household
• I See No Stores
• Suggestions Or Zones Look Wrong
• Image Upload Failed
• CORS Error
• Migration Or Store Management Is Unavailable
• Gitea Actions Failed
• API Returned 401 Or 403
• API Returned 500

Troubleshooting

Use this page for common user, admin, and developer problems.

I Cannot Log In

Check:

• Username is lowercase or can be lowercased by the app.
• Password is correct.
• Backend is running.
• JWT_SECRET is configured.
• The browser can reach the backend API URL.
• Cookies are not blocked for the app origin.

For developers, inspect the response status and request_id. Do not log session cookies or tokens.

I Am Logged Out Unexpectedly

Possible causes:

• Session expired.
• Session row was deleted.
• Backend SESSION_COOKIE_NAME changed.
• Browser cookie storage was cleared.
• Frontend and backend origins changed and cookies no longer match CORS/cookie rules.

Log in again after confirming the backend is healthy.

I Have No Household

Create a household or open an invite link. If invite links fail:

• Confirm the link has not expired.
• Confirm the household join policy accepts new joins.
• If approval is required, wait for an owner/admin to approve the request.

I See No Stores

This means the active household has no usable store location.

1. Confirm the active household is correct.
2. Ask an owner/admin to open Manage > Stores.
3. Add a store and location.
4. Set a default location if needed.

Suggestions Or Zones Look Wrong

Check:

• Active household.
• Active store location.
• Location zones in Manage > Stores.
• Available items in Manage > Stores > Manage Items.
• Whether current list items should be imported into the catalog.

Image Upload Failed

Check:

• Browser network status.
• File type and size.
• /config image limit values.
• Upload toaster state.
• Retry the queued upload.

Developers should check the backend image middleware and the request ID from the failed response. Do not log image bytes.

CORS Error

Backend CORS uses ALLOWED_ORIGINS.

Add the exact frontend origin, for example:

http://localhost:3010
http://127.0.0.1:3010
http://localhost:5173

After backend env/CORS changes in Docker dev, recreate the backend service:

docker compose -f docker-compose.dev.yml up -d --force-recreate --no-deps backend

Then verify:

curl http://127.0.0.1:5000/
curl http://127.0.0.1:5000/config

Migration Or Store Management Is Unavailable

Some store/catalog features require the latest database schema.

Check:

npm run db:migrate:status
npm run db:migrate:verify

Only run npm run db:migrate when the operator intends to apply migrations to the selected external Postgres database.

Gitea Actions Failed

Check the failing job:

• Install dependencies.
• Audit.
• Lint.
• Typecheck.
• Backend tests.
• Migration stale check.
• Backend build.
• Frontend build.
• Docker image build/push.
• SSH deploy.

For deployment failures, verify Gitea secrets exist and are current. Do not print secret values in logs.

API Returned 401 Or 403

401 means the request is not authenticated. 403 means the authenticated user lacks the required role or membership.

Check:

• User is logged in.
• Session cookie is present.
• Token in local storage is current.
• User belongs to the target household.
• User has owner/admin role for management actions.
• System admin user has the system_admin role for /admin.

API Returned 500

Use the request_id in the response and backend logs to trace the failure.

Common causes:

• Missing environment variable.
• Database connection failure.
• Pending migration.
• Invalid data shape not handled by the route/controller.
• Image processing failure.