Troubleshooting

The problems people meet most often, and how to fix each one.

"AUTH_SECRET is missing or too short"

The .env file is missing, or AUTH_SECRET has fewer than 16 characters. Create .env from .env.example and set a long random value. Restart the server after changing .env.

"Settings row missing: run npm run db:seed"

The database exists but is empty. Run npm run db:seed. It creates the settings, the sample store and the owner account, and never overwrites existing rows.

I cannot sign in to the dashboard

  • The owner account is created only when the staff table is empty. If you changed OWNER_PASSWORD after the first seed, the old password still applies.

  • To reset it, open a terminal in the project and run:

    node -e 'const{scryptSync,randomBytes}=require("crypto");const s=randomBytes(16);console.log("scrypt$"+s.toString("hex")+"$"+scryptSync("NEW-PASSWORD-HERE",s,64).toString("hex"))'
    

    Then put the printed value in the passwordHash column of your account with npx prisma studio.

  • After 10 attempts in a minute from the same address, sign-in is paused for a minute.

A page shows "Not available for your role"

The account's role does not have that section. The owner can change it in Dashboard > Admin roles. Changes apply at once.

Card payment does not appear at checkout

All three must be true: Settings > Card payments is on, THAWANI_SECRET_KEY and THAWANI_PUBLISHABLE_KEY are set in .env, and the currency is OMR. See Payments.

A paid card order still says "waiting for payment"

The order is marked paid only after the server asks Thawani about the session. If the customer closed the browser before returning, open the order in the dashboard: the payment reference is the Thawani session id, which you can check in the Thawani portal. Check also that SITE_URL is your public https:// address, because Thawani sends the customer back there.

Uploaded images return 404 after a deploy

public/uploads was replaced by the new version. Keep that folder between deploys (see Manual setup).

"Too many requests"

Checkout allows 20 orders per minute from one address, the contact form 5 per 10 minutes, sign-in 10 per minute. Behind a proxy, make sure it sends X-Forwarded-For, or all visitors count as one.

Arabic text shows in the wrong direction

Codes, SKUs and phone numbers use the ltr-nums class to stay left to right inside Arabic text. If you add new fields with mixed text, wrap them the same way (see Languages).

The build fails after editing a page

Run npx tsc --noEmit to see type errors with file and line. Route files under src/app/api may only export HTTP handlers (GET, POST...) and settings like dynamic; put shared code in src/lib.

The e2e test fails on a store I have used

scripts/e2e_api.py expects the sample catalogue (for example the "Linen kaftan" product and the WELCOME10 coupon). Run it on a fresh demo database: delete prisma/souq.db, run npm run setup, start the server, run the test.