# 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

Source: https://anasaki.live/docs/en/studio/troubleshooting

## Read the logs first

```sh
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

| Problem | Cause / fix |
| --- | --- |
| `docker compose up` says `set JWT_SECRET` / `set MYSQL_PASSWORD` / `set CODE_DB_PASSWORD` | Required values are missing from `.env` (or `.env` is not next to `docker-compose.yml`) — see [.env variables](/docs/en/studio/env-variables) |
| studio keeps waiting / cannot reach the database | MySQL 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 refuses | The 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 open | The port is taken — change `PORT` in `.env`; or the server's firewall blocks it |
| A second site on the same machine replaced the first | Give each folder a different `COMPOSE_PROJECT_NAME` and `PORT` |

## Getting into the admin

| Problem | Cause / fix |
| --- | --- |
| Forgot the changed admin address (`/admin` is a 404) | Put `ADMIN_PATH=admin` in `.env` and run `docker compose up -d` ([Security](/docs/en/studio/site-settings)) |
| Everyone was signed out at once | `JWT_SECRET` changed — expected; sign in again |
| Sign-in refused with &#34;too many failed attempts&#34; | 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 &#34;Behind a reverse proxy&#34; below |
| Must sign in again after upgrading to 2.3.0 | Expected: 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 up | Ask another administrator to set a new password under **Users** |
| Signing in says the account is suspended | An administrator suspended it — they press **Activate** on the Users page. Every attempt is in the **Activity log** |

## Email

| Problem | Cause / fix |
| --- | --- |
| The test email fails | Check the server, port and encryption; Gmail needs an &#34;App password&#34;; 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 email | Check the spam folder; reset links last 2 hours, welcome links 3 days |

## Behind a reverse proxy

| Problem | Cause / fix |
| --- | --- |
| Everyone comes from one IP in statistics / sign-in is limited for the whole site | Set `TRUST_PROXY=true` (only when port 8090 is not reachable directly). Behind Cloudflare see [Behind Cloudflare](/docs/en/studio/env-variables) |
| A script calling the API gets `403 error code: 1010` | Cloudflare 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 fail | The proxy limits the request size (e.g. Nginx `client_max_body_size`) — raise it above &#34;Maximum file size&#34; in Site settings → Files & media |

## Plugins

| Problem | Cause / fix |
| --- | --- |
| The plugin store says it cannot reach the Store | The server has no internet access — you can still install a `.zip` on the **Upload .zip** tab |
| &#34;The package signature is not valid&#34; / &#34;sent without a signature&#34; | 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](/docs/en/store/install-plugins)) |
| A plugin switched itself off after an update | The new version asks for more permissions — press **Approve and activate** ([Plugin permissions](/docs/en/store/plugin-permissions)) |
| Activation fails / needs another plugin first | Install and activate the required plugins first (the dialog offers **Install all**) |
| The &#34;N plugins are waiting to move…&#34; banner stays | See [Updating and moving from the built-in plugins](/docs/en/studio/upgrade) |
| A plugin block disappeared from a page | The plugin was switched off or removed — switch it on again and the block comes back |

## Site Code

| Problem | Cause / fix |
| --- | --- |
| Published code broke the site | Turn on **Safe mode** on the Site Code page; if the admin itself is unreachable, add `SITE_CODE_DISABLED: &#34;true&#34;` under `environment:` of the `studio` service in `docker-compose.yml` and run `docker compose up -d` |
| The database page says &#34;fallback mode&#34; and the SQL console is unavailable | The separate database is not set up yet — see [The Site Code database](/docs/en/developers/database) |
| Saved secrets cannot be read after moving servers | `site-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](/docs/en/developers/site-code) and [anasaki-code CLI](/docs/en/developers/cli).
