Anasaki Studio

Settings and maintenance

Troubleshooting

Common problems when installing and running Anasaki Studio, with causes and fixes — from a system that won't start and a forgotten admin address to email that never arrives

8 min readLast updated

View as Markdown

On this page

Read the logs first#

docker compose ps                 # status of both containers (mysql, studio)
docker compose logs -f studio     # Anasaki Studio's log
docker compose logs mysql         # the database's log

Installing and starting#

ProblemCause / fix
docker compose up says set JWT_SECRET / set MYSQL_PASSWORD / set CODE_DB_PASSWORDRequired values are missing from .env (or .env is not next to docker-compose.yml) — see .env variables
studio keeps waiting / cannot reach the databaseMySQL has not finished starting (studio waits for its health check) — see docker compose logs mysql. Special characters in passwords can break the connection string; use letters and digits only
Changed MYSQL_PASSWORD and the database refusesThe password is read only when the database is first created. Use the old value, or change the password in MySQL yourself to match
http://…:8090 does not openThe port is taken — change PORT in .env; or the server's firewall blocks it
A second site on the same machine replaced the firstGive each folder a different COMPOSE_PROJECT_NAME and PORT

Getting into the admin#

ProblemCause / fix
Forgot the changed admin address (/admin is a 404)Put ADMIN_PATH=admin in .env and run docker compose up -d (Security)
Everyone was signed out at onceJWT_SECRET changed — expected; sign in again
Sign-in refused with "too many failed attempts"10 wrong passwords in 15 minutes from one IP (answers slow down from the 4th). Wait 15 minutes or sign in from another network — if it happens to everyone at once, see "Behind a reverse proxy" below
Must sign in again after upgrading to 2.3.0Expected: the admin keeps its session in an HttpOnly cookie instead of localStorage (page scripts cannot read it). Sign in once — scripts and the CLI keep using Authorization: Bearer
Forgot the password and email is not set upAsk another administrator to set a new password under Users
Signing in says the account is suspendedAn administrator suspended it — they press Activate on the Users page. Every attempt is in the Activity log

Email#

ProblemCause / fix
The test email failsCheck the server, port and encryption; Gmail needs an "App password"; some VPSes block outgoing ports 25/465/587
Password-reset links point at the wrong address (e.g. localhost)Set SITE_URL=https://your-domain in .env
Users don't see the emailCheck the spam folder; reset links last 2 hours, welcome links 3 days

Behind a reverse proxy#

ProblemCause / fix
Everyone comes from one IP in statistics / sign-in is limited for the whole siteSet TRUST_PROXY=true (only when port 8090 is not reachable directly). Behind Cloudflare see Behind Cloudflare
A script calling the API gets 403 error code: 1010Cloudflare blocks the library's default User-Agent — send your own, e.g. my-script/1.0
Browsers don't enforce https (header Strict-Transport-Security: max-age=0)Cloudflare's HSTS has Max Age 0 — fix it in Cloudflare → SSL/TLS → Edge Certificates
Large uploads failThe proxy limits the request size (e.g. Nginx client_max_body_size) — raise it above "Maximum file size" in Site settings → Files & media

Plugins#

ProblemCause / fix
The plugin store says it cannot reach the StoreThe server has no internet access — you can still install a .zip on the Upload .zip tab
"The package signature is not valid" / "sent without a signature"The package was changed on the way or does not come from the store the site trusts (CMS 2.4.0). Try again; with your own store check STORE_URL / STORE_PUBLIC_KEY (Installing plugins)
A plugin switched itself off after an updateThe new version asks for more permissions — press Approve and activate (Plugin permissions)
Activation fails / needs another plugin firstInstall and activate the required plugins first (the dialog offers Install all)
The "N plugins are waiting to move…" banner staysSee Updating and moving from the built-in plugins
A plugin block disappeared from a pageThe plugin was switched off or removed — switch it on again and the block comes back

Site Code#

ProblemCause / fix
Published code broke the siteTurn on Safe mode on the Site Code page; if the admin itself is unreachable, add SITE_CODE_DISABLED: "true" under environment: of the studio service in docker-compose.yml and run docker compose up -d
The database page says "fallback mode" and the SQL console is unavailableThe separate database is not set up yet — see The Site Code database
Saved secrets cannot be read after moving serverssite-code.key (or SITE_CODE_SECRET_KEY) did not come along — use the old key, or enter the secrets again

For other developer problems see Site Code and anasaki-code CLI.