local authentication troubleshooting guide

follow these steps systematically to identify and resolve issues where local authentication fails or returns “invalid jwt token”.

1. environment cleanup & base setup

if you suspect your environment is “dirty” or has stale configurations, start by clearing the cache and rebuilding:

purge docker cache:
```
docker system prune --all --volumes
```

verify linkages: ensure the correct configuration files are linked:


ln -s docker-compose.yml ./docker/local/docker-compose/docker-compose.yaml
ln -s docker/local/.env .env.local

check auth.json: ensure a valid auth.json exists for github authentication:
```
{
  "github-oauth": {
    "github.com": "$github_access_token"
  }
}
```
(note: replace $github_access_token with your actual plain-text token if necessary.)

reinstall & migrate:


# install dependencies
./composer install
# run migrations (dry run first if needed)
./console doctrine:migrations:migrate -n
# reset dynamodb tables
./console phpc:dynamo-db:tables:delete-all

2. environment variable verification

failures often stem from incorrect environment variables not being loaded or recognized.

check local file

verify .env.local contains the correct values:

app_env: must be local (not dev).
tenant: must match the login-faker tenant (e.g., demo1).
jwt_security_faker_enabled: must be true (enabled).

verify inside container

even if the file is correct, the container might not have picked up the changes. enter the container and check:


./exec sh
# inside the container:
echo "$app_env"
echo "$tenant"
echo "$jwt_security_faker_enabled"

if values are incorrect inside the container, update the docker-compose file and rebuild.

3. database & identity verification

if the jwt is valid but the user cannot access the system, check the database records:

user slugs: ensure the user’s slug in the database is correctly set and matches the records in both the account_user and user tables.
slug alignment: ensure the slug extracted from the token matches the user’s actual identifier in the application.

4. token & session validation

use these commands to verify if the system is issuing valid tokens.

get token via login faker:
- for included with phpr, port 8009: curl -c - localhost:8009/login | grep currentuser
- for standalone loginfaker, port 8035: curl -c - localhost:8035/login | grep currentuser
check browser cookies:
- verify that a jwt is present.
- verify that the slug in the cookie matches the user’s slug.
manual validation:
- check expiration: ensure the token hasn’t expired.
- check tenant: ensure the tenant matches the expected local environment.

last updated: 2026-09-01