Troubleshooting

This guide covers the most common problems operators will hit when deploying or evaluating MatrixEasyMode.

MatrixEasyMode is currently designed for serious self-hosters and infrastructure-capable operators. That means the troubleshooting model is explicit:

• check current state
• inspect infrastructure logs
• inspect app logs
• verify environment values
• verify NPM and certificate state
• verify public URLs and DNS

If you have not completed the normal install flow yet, start with:

• Get Started
• Installation Guide
• Advanced Install

First diagnostic checks

Before diving into specific issues, run these commands:

./stack.sh status
./stack.sh logs infra
./stack.sh logs app

If you are working in local mode and want direct Compose inspection:

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app ps
docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app logs -f api web

These usually tell you whether the issue is:

• infrastructure not running
• app layer not starting
• bad environment values
• NPM integration failure
• local build failure

Understand the deployment order

MatrixEasyMode depends on a staged startup model:

1. infrastructure first
   • PostgreSQL
   • Nginx Proxy Manager
2. application second
   • MatrixEasyMode API
   • MatrixEasyMode web frontend

If the app layer starts too early, you can get failures that look like app issues but are really ingress or certificate readiness problems.

Common problems

The app layer was started too early

Symptoms

You may see:

• API startup retries
• ingress bootstrap failures
• route publish failures
• missing certificate errors
• NPM-related 400 or authentication errors

What to check

Confirm:

• infrastructure is already running
• NPM is reachable
• you can log into NPM
• the wildcard certificate already exists in NPM
• INGRESS_CERTIFICATE_NAME matches the certificate name in NPM

What to do

Bring up infrastructure first:

./stack.sh up infra

Then complete the NPM certificate setup before starting the app layer:

./stack.sh up app

Nginx Proxy Manager certificate is missing

Symptoms

The platform ingress bootstrap cannot finish cleanly, even though the app containers may appear to be running.

What to check

Review .env:

cat .env

Confirm the configured certificate name:

INGRESS_CERTIFICATE_NAME=*.your-domain.com

Then log into NPM and confirm that certificate actually exists with the same name.

What to do

Create the wildcard certificate in NPM before starting the app layer.

This is a hard requirement of the current deployment model.

NPM credentials are wrong

Symptoms

The API cannot authenticate against NPM, route bootstrap fails, or route creation/update calls fail.

What to check

Inspect these values in .env:

• NPM_IDENTITY
• NPM_SECRET
• NPM_BASEURL

Make sure:

• the identity is a real operator account in NPM
• the password/secret is correct
• the base URL is reachable from the API container

Bundled default:

NPM_BASEURL=http://npm:81/api

What to do

Correct the values in .env, then restart the app layer:

./stack.sh down app
./stack.sh up app

Public URLs are wrong

Symptoms

You may see:

• frontend loads incorrectly
• auth callbacks fail
• browser API calls go to the wrong host
• redirects go to localhost or the wrong domain

What to check

Inspect these values:

• NEXTAUTH_URL
• NEXT_PUBLIC_API_URL
• NEXT_PUBLIC_SERVER_URL

Typical production-style values look like:

NEXTAUTH_URL=https://admin.your-domain.com
NEXT_PUBLIC_API_URL=https://api.your-domain.com
NEXT_PUBLIC_SERVER_URL=https://admin.your-domain.com

What to do

Make sure public URLs are real, operator-managed hostnames and not leftover localhost values from development.

After correcting .env, restart the app layer.

DNS is wrong or incomplete

Symptoms

• public URLs do not resolve correctly
• browser access fails
• certificates do not validate as expected
• the deployment looks healthy internally but is not reachable publicly

What to check

Verify that your public hosts point at the correct server:

• admin.your-domain.com
• api.your-domain.com

Also confirm that ports 80 and 443 are reachable as required by your environment.

What to do

Fix DNS first. Do not keep troubleshooting the application layer if the public hostname layer is still incorrect.

Local mode images were not built

Symptoms

In local mode, the app layer fails to start or uses image names that do not exist locally.

What to check

Inspect:

• MEM_IMAGE_SOURCE
• MEM_API_IMAGE
• MEM_WEB_IMAGE

If MEM_IMAGE_SOURCE=local, confirm that local images were built:

./stack.sh build app

What to do

Build the images first:

./stack.sh build app

Then start or restart the app layer:

./stack.sh up app

Local repository layout does not match docker-compose.local.yml

Symptoms

Local builds fail even though local mode is enabled correctly.

What to check

Review the build contexts in:

docker-compose.local.yml

Confirm that the referenced local source repositories actually exist where the compose file expects them.

What to do

Adjust the build contexts in docker-compose.local.yml to match your real local directory layout, then rebuild.

PostgreSQL container is running but the app cannot use it

Symptoms

The API does not fully start, or database-related failures appear in app logs.

What to check

Inspect:

• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_DB

Make sure the values in .env line up with the bundled PostgreSQL container and the API configuration.

Also check infrastructure logs:

./stack.sh logs infra

What to do

If the problem is an environment mismatch, correct .env and restart the app layer. If PostgreSQL itself failed to start, address that first before troubleshooting the API.

Auth state is broken or callbacks fail

Symptoms

• sign-in does not complete
• redirects are wrong
• session handling appears inconsistent

What to check

Inspect:

• NEXTAUTH_URL
• NEXTAUTH_URL_INTERNAL
• NEXTAUTH_SECRET
• AUTH_TRUST_HOST

Typical values:

NEXTAUTH_URL=https://admin.your-domain.com
NEXTAUTH_URL_INTERNAL=http://web:3000
AUTH_TRUST_HOST=true

What to do

Make sure the public URL is correct, the internal callback host remains on the Docker service name unless intentionally changed, and the secret is valid.

API or web container starts, but public route still does not work

Symptoms

Containers appear healthy, but public browser access still fails.

What to check

Confirm all of the following together:

• the route exists in NPM
• the route points to the correct backend container and port
• the wildcard certificate is attached correctly
• public DNS resolves correctly
• the public URLs in .env match the route names you expect

What to do

Treat this as an ingress-layer problem first, not an application problem.

Useful commands

Check current state

./stack.sh status

Follow infrastructure logs

./stack.sh logs infra

Follow application logs

./stack.sh logs app

Follow a specific service

./stack.sh logs api
./stack.sh logs web
./stack.sh logs postgres
./stack.sh logs npm

Restart the app layer

./stack.sh restart app

Stop and start the app layer manually

./stack.sh down app
./stack.sh up app

Troubleshooting by mode

Registry mode

If you are using published images, focus on:

• image registry and tag values
• public URLs
• NPM credentials
• certificate state
• DNS
• staged startup order

Relevant values:

• MEM_IMAGE_SOURCE=registry
• MEM_REGISTRY
• MEM_VERSION

Local mode

If you are using local images, focus on:

• whether images were built
• whether the tags match .env
• whether docker-compose.local.yml points to valid local repositories
• whether the local override file is included in every relevant command

Relevant values:

• MEM_IMAGE_SOURCE=local
• MEM_API_IMAGE
• MEM_WEB_IMAGE

A good operator troubleshooting sequence

Use this sequence when something is wrong:

1. inspect current state

   bash

   bash

   ./stack.sh status

2. inspect infrastructure logs

   bash

   bash

   ./stack.sh logs infra

3. inspect app logs

   bash

   bash

   ./stack.sh logs app

4. review .env

   bash

   bash

   cat .env

5. confirm NPM is reachable, credentials work, and the wildcard certificate exists

6. confirm public URLs and DNS

7. if using local mode, confirm the images were built and build contexts are valid

If the problem still is not obvious

At that point, narrow it down by layer:

• environment layer: wrong .env values
• infrastructure layer: PostgreSQL or NPM not healthy
• ingress layer: certificate, route, or DNS issue
• application layer: API or web startup problem
• local build layer: missing or mis-tagged local images

Troubleshooting gets much easier once you identify which layer is actually failing.

Related documentation

• Get Started
• Installation Guide
• Advanced Install
• Configuration
• Network Behavior