Troubleshooting
In short. Find the message you see in the left column of a table, then do what the right column says. The tables cover the app that does not start, trading that stays off, and deploy commands that fail.Each fix that changes
sesame.env ends the same way: run task deploy:start on your
computer (Change a setting).
The deploy stops and the app does not start
The app checks its settings when it starts. It stops if a setting is wrong.-
On your computer, read the app’s log:
task deploy:logs -- sesame -
Find the line
sesame serve: invalid config:. Each line after it names one wrong setting. -
On the server, correct each setting:
sudoedit /opt/sesame/sesame.env -
On your computer, start the app again:
task deploy:start
| What you see | What it means | What to do |
|---|---|---|
UI_PASSWORD_HASH: required | The password hash is missing | Add it (First deploy, step 3) |
UI_PASSWORD_HASH: not an argon2id PHC string | The hash has no single quotes around it, or it is not complete | Paste the full hash again, inside single quotes |
SESSION_SECRET: required | The session secret is missing | Add it (First deploy, step 3) |
SESSION_SECRET: decodes to 16 bytes, need at least 32, or SESSION_SECRET: not hex or base64 | The secret is too short or is not random hex | Use the output of openssl rand -hex 32 |
TELEGRAM_CHAT_ID: empty while TELEGRAM_BOT_TOKEN is set; set both or neither, or the reverse | Only one of the two Telegram settings has a value | Add the other one, or remove both |
TELEGRAM_BOT_TOKEN: not a Bot API token (digits, a colon, then the secret) | The token is not complete | Copy the full token from @BotFather |
TELEGRAM_CHAT_ID: must be a numeric chat id, negative for a group | The chat id is a name or has other characters | Use the number. Keep the minus sign if it has one |
POLY_BUILDER_API_KEY: set, but fund-moving features (relayer, bridge) are out of scope; remove the variable | A Builder, relayer or bridge setting is in the file. An empty value counts too. The app never moves money | Delete that line. The message names the setting |
GEOBLOCK_URL: no longer configurable | An old setting is in the file | Delete the line |
POLYMARKET_PRIVATE_KEY: renamed to POLYMARKET_SESSION_KEY | An old name is in the file | Make sure that the value is a Session Key, not the owner key. Then rename the line to POLYMARKET_SESSION_KEY |
POLYMARKET_SESSION_KEY: must be 32 bytes as 64 hex characters (optional 0x), got 40 characters | An address is in the line, not the private key | Paste the Session Key’s private key |
POLYMARKET_SESSION_KEY: must be 32 bytes as 64 hex characters (optional 0x), got a non-hex character | The key has a wrong character, a space or quotes | Paste the private key again, with nothing around it |
POLYMARKET_SESSION_KEY: its address 0x… equals POLYMARKET_OWNER_ADDRESS | The owner key is in the file | Remove it now. Treat the owner key as exposed and follow the incident runbook. Use a Session Key |
POLYMARKET_WALLET_ADDRESS: required with POLYMARKET_SESSION_KEY or the CLOB credentials | The wallet address is missing | Add the Deposit Wallet address |
POLYMARKET_WALLET_ADDRESS: equals POLYMARKET_OWNER_ADDRESS; it must be the account's Deposit Wallet | The owner’s address is in the wallet line | Use the Deposit Wallet address from the profile menu on polymarket.com |
POLYMARKET_WALLET_ADDRESS: equals the signer address | The Session Key’s address is in the wallet line | Use the Deposit Wallet address from the profile menu on polymarket.com |
POLYMARKET_WALLET_ADDRESS: not a 20-byte hex address, or the same for POLYMARKET_OWNER_ADDRESS | The address is not 40 hex characters | Copy the address again |
RISK_CEILING_ORDER_NOTIONAL: must be a pUSD decimal with at most 6 places, got "50,000" | A number has a thousands separator | Write 50000 |
BACKUP_INTERVAL: must be 0 or at least 1m0s, got "30s" | The backup interval is too short | Use 0 or at least 1m |
migrate /data/sesame.db: database user_version … is newer than the … known migrations | You went back to a release that is older than the data | Install the newer release again, or restore the backup from before the update (Go back to the previous release) |
The app runs but trading stays off
The app shows why trading is off in these places:- The top bar: Trading off, or Geoblocked and the country.
- The tooltip of the trading switch and of each price button.
- Settings, then Session, then Trading: Off.
| What you see | What it means | What to do |
|---|---|---|
Trading off · LIVE_TRADING is not set | LIVE_TRADING is not exactly true | Do Go live, step 6 |
Trading off · geoblocked | Polymarket reports that the server’s location is blocked. Or the location check failed: then https://<your-domain>/api/health shows degraded | Do step 1 of Prepare the server on the server. A blocked server must move to a permitted region. Never add a proxy or a VPN |
Trading off · clock differs from the venue | The server’s clock is wrong | On the server, run sudo timedatectl set-ntp true |
Trading off · Session Key expired | A Session Key is valid for 180 days | Replace the key |
Trading off · venue credentials unavailable | The app has no working Session Key. Settings, then Account, then Credentials shows Not connected, Connecting or Account error with the reason. wallet_mismatch means that Polymarket does not list this key as a signer of POLYMARKET_WALLET_ADDRESS | Check the settings from Go live, step 3. For each reason, see Session Key troubleshooting |
Trading paused · activity outside this app | The app saw a trade or a transfer that it did not make. It went to Safe | See Trading switched to Safe after activity outside this app |
Safe: arm to trade | Trading is on. The switch is at Safe, as after each start | Arm the switch to trade |
Deploy commands fail
| What you see | What it means | What to do |
|---|---|---|
Host key verification failed | Your computer does not know the server’s fingerprint, or the fingerprint changed | Compare it with the provider’s web console (step 12) before you accept it |
deploy: SESAME_ALLOWED_SIGNERS must name your allowed_signers file | The setting is missing, or the file is empty | First deploy, step 1 |
deploy: SESAME_DEPLOY_HOST is not set, or deploy: SESAME_DEPLOY_KEY is not set | A setting is missing in deploy/.deploy.env | First deploy, step 1 |
deploy: no usable release tag | Your computer has no release-* tag | Run git fetch origin 'refs/tags/release-*:refs/tags/release-*', or name a tag |
deploy: tag <tag> is a signed tag object for another name | The tag was signed under another name | Sign a new tag (step 8) |
deploy: the deploy key … has no passphrase and is not a FIDO2 (sk-) key | The key file has no protection | Add a passphrase: ssh-keygen -p -f ~/.ssh/sesame_deploy |
deploy: run this by hand in a terminal | The command ran without a terminal | Type the command yourself in a terminal |
deploy: restore not confirmed | You did not type y | Run the restore again and type y |
sesame-deploy-shell: refused: not an allowed sesamectl command | The server accepts only the day-to-day commands | Use one of them |
sudo: a password is required | The sudoers rule is missing | Step 10 |
sesamectl: another sesamectl run is in progress | A deploy, a restore or a backup encryption runs now | Wait, then try again |
sesamectl: … must be owned by root:root and not writable by group or others | A settings file or folder has the wrong owner | On the server, run sudo chown root:root <path> and sudo chmod go-w <path> |
sesamectl: missing /opt/sesame/sesame.env | The settings file does not exist | First deploy, step 3 |
sesamectl: /opt/sesame/sesame.env must be root:root 0600 | Other accounts can read the settings file | On the server, run sudo chmod 0600 /opt/sesame/sesame.env and sudo chown root:root /opt/sesame/sesame.env |
sesamectl: /opt/sesame/sesame.env sets a proxy variable; remove it | A *_PROXY line is in the file | Delete it |
sesamectl: /root/.docker/config.json has a proxies entry; remove it | Docker on the server is set to use a proxy | Remove the proxies entry from that file |
sesamectl: tag … has no valid signature from /etc/sesame/allowed_signers | Your key did not sign the tag | Sign it |
sesamectl: fetching tag … failed | The tag is not pushed. Or the tag changed after the server fetched it | Push the tag. Or sign a new tag with a new name |
sesamectl: images for <tag> are not on this server | That release was never built on this server, or it was deleted | Run task deploy -- <tag> |
sesamectl: no previous tag recorded | The server has no previous release | Name a tag: task deploy:rollback -- <tag> |
sesamectl: restore failed and sesame is stopped | The restore was refused. The lines above it give the reason | Run task deploy:start. If the lines start restore refused:, see Backups that fail the MAC check |
sesamectl: a file named … already exists | A backup with that name is already on the server | Restore it by name, or rename your file |
sesamectl: the outbox holds 128 files; lower BACKUP_KEEP … | Too many backups wait for the backup machine | Lower BACKUP_KEEP in sesame.env (configuration.md) and run task deploy:start. The next scheduled backup deletes the old backups and their encrypted copies |
| No padlock, or certificate errors | DNS does not point at the server yet. Or the CAA record is wrong. Or ports 80 and 443 are closed | Steps 3 and 4. Then read task deploy:logs -- caddy |
403 with origin not allowed | You opened the site with another name | Open https://<your-domain> exactly |
421 with host not allowed | The request named a host other than DOMAIN | Check DOMAIN in /etc/sesame/deploy.conf |