Skip to content

Troubleshooting ​

Most problems come down to one process not running or one setting not matching. Start with the quick health check, then find your symptom below.

ReferenceServer administrationDevOpsVerified against the platform code

Quick health check ​

Run these four commands first. They answer most questions:

bash
cd /var/www/exchange
pm2w status                         # every process online?
php artisan horizon:status          # Horizon running?
php artisan schedule:list | head    # scheduler configured?
tail -n 50 storage/logs/laravel-$(date +%F).log # latest errors (today's file)

Then open Admin → System Monitor, which tests the database, Redis, cache, queues, email, price feeds, every blockchain API and more in one go. See System Monitor.

pm2w is the alias from Installation → Prepare PM2.

"Server Error" (500) pages ​

  1. Read the log: tail -n 100 storage/logs/laravel-$(date +%F).log (one file per day). The newest error is at the bottom.
  2. Nothing there? Check the web server logs: /var/log/nginx/error.log and /var/log/php8.3-fpm.log.
Error in the logFix
Permission denied on storage/ or bootstrap/cachesudo chown -R www-data:www-data storage bootstrap/cache
No application encryption keyphp artisan key:generate (only on a new install, never on a running one)
SQLSTATE[08006] / connection refusedPostgreSQL is down, or the DB_* values are wrong
Connection refused [tcp://127.0.0.1:6379]Redis is down: sudo systemctl start redis-server
Class "…" not found after an updatecomposer install --optimize-autoloader then php artisan optimize:clear

Don't debug with APP_DEBUG on a live site

APP_DEBUG=true shows full error details, including secrets, to every visitor. Read the log instead. If you must turn it on, do it for a few minutes, with maintenance mode on.

Users get logged out at once, or can't sign in ​

SESSION_DRIVER or CACHE_DRIVER is still array (the .env.example value), which forgets everything after each request. Set both to redis and run php artisan config:clear.

Also check SANCTUM_STATEFUL_DOMAINS: it must be your domain (for example yourdomain.com), or the site's own API calls are rejected.

Admin panel returns 404 ​

USER_ASSETS in .env is "true". Then the server doesn't load the admin addresses at all. Set it to "false" and run php artisan config:clear and php artisan route:clear. See Building assets.

Orders don't fill, or appear late ​

CheckFix
order-processor and horizon online in pm2w status?If not, check the scheduler (below). pm:watcher starts them every minute.
Long waits on the orders queue in the Horizon dashboard (/horizoncctech)The server is short of CPU, or needs more workers. See Queues → Scaling.
Liquidity market, but no bot orders in the bookAdmin → Market services: is the market Live, and is Liquidity (provider markets) running? pm2w logs liquidity-binance. The server must reach api.binance.com and stream.binance.com:9443.
A service says Not respondingIts process runs but its loop stopped. It's restarted automatically within 5 minutes; press Restart to do it now and check pm2w logs <name> and storage/logs/laravel-YYYY-MM-DD.log for the cause (the card shows its last error).
Matching engine enabledphp artisan matching-engine:status. See Matching engine.

Queues not processing ​

  • QUEUE_CONNECTION must be redis (not sync).
  • APP_ENV must be production or local, or Horizon starts no workers.
  • After changing .env: php artisan config:clear && php artisan horizon:terminate.

More in Queues (Horizon).

Scheduler not running ​

Signs: core processes never start, deposits are never detected, mini-charts stay empty, staking rewards don't arrive.

bash
sudo crontab -u www-data -l    # the schedule:run line must be there
grep CRON /var/log/syslog | tail
sudo -u www-data php artisan schedule:run   # run it once by hand and read the output

If processes still don't start: check PM_PATH, PM_PHP_PATH and PM_USR_PATH in .env (see Installation → Prepare PM2), and that PM_SERVICE_WATCHER_ENABLED isn't false.

Market services page shows everything stopped ​

The processes are running under a different PM2 home, usually because they were started as root with plain pm2. The platform only sees processes in $PM_PATH/.pm2 belonging to www-data. Stop the root copies (sudo pm2 delete all) and let pm:watcher start them correctly within a minute.

Charts are empty ​

See Chart service → Troubleshooting. In short: provider-type markets need the chart process and the /chart.io Nginx block. Internal markets need trades, or External chart data switched on.

Prices aren't live / "Connection lost" ​

The status bar on the trade page shows Connection lost when the browser can't reach Soketi. See Real-time → Fixing "Connection lost". The usual causes are Soketi not running, a missing certificate on socket.yourdomain.com, or mismatched keys followed by a missing rebuild.

Markets page mini-charts are empty ​

They're built by markets:sparklines every two hours. Right after installation, fill them at once:

bash
php artisan markets:sparklines-seed

Deposits don't arrive ​

Work through this in order:

  1. The transaction is confirmed on the block explorer, to the address shown in the user's deposit screen, on the right network.
  2. Deposits are open: the network (Networks) and the currency on that network (Currencies) both have deposits on.
  3. The amount is at least the minimum deposit for that currency and network.
  4. The scheduler runs (see above). Run the scan by hand and read its output, for example php artisan deposits:scan trc20 (it prints how many transfers it saw and credited).
  5. Explorer API keys are set for Ethereum, BNB Smart Chain and Polygon: APP_ETHERSCAN_KEY, APP_BSCSCAN_KEY, APP_POLYGONSCAN_KEY (one key, or several comma-separated: they share the hour). Errors from the explorer are written to the daily log (storage/logs/laravel-YYYY-MM-DD.log).
  6. The bridge runs: pm2w status → bridge-<network> online.
  7. XRP or TON: their deposit monitors aren't scheduled by default. See Bridges → XRP and TON. The user must also have included their memo.
  8. Bitcoin: the node's walletnotify must call the platform. See Bridges → Bitcoin.

Token deposits detected but stuck "pending" ​

Collecting a token deposit first sends a little of the network's coin (ETH, BNB, TRX, POL, SOL) from the hot wallet to the user's address. If the hot wallet is out of that coin, the transfer can't start and the bridge marks the deposit's transfer fee_error (or failed). The user's balance is not affected (the deposit is already credited); only the collection waits. Top the hot wallet up, then queue those transfers again:

bash
php artisan deposits:sweep trc20 --retry   # or the network's slug / id; without one: every network

Withdrawals stuck ​

  • Waiting for approval: every crypto withdrawal waits for an admin. Approve them in Reports → Deposits & withdrawals. Automatic approval needs ENABLE_AUTO_WITHDRAWALS=true.
  • "Insufficient funds" instead of Approve: the hot wallet holds less than the amount. Top it up.
  • Sending / Needs review: the platform couldn't tell whether the bridge sent it (timeout, crash, or no transaction 2 hours after sending). The amount stays held. Check the hot wallet on the explorer, then Mark as sent with the hash or Refund it. See Approvals → Needs review.
  • Waiting provider approval: sent, waiting for the network. withdrawals:sync finishes it once the bridge has written the transaction. Check the scheduler and the bridge.
  • Failed: the bridge refused it. The amount was returned to the user once (also when the bridge marks it failed later), and the reason is saved on the withdrawal.

Emails don't send ​

  1. Use the test in Admin → System Monitor, which sends a test email.
  2. Horizon must run. Almost every email is queued, so nothing is sent while Horizon is down.
  3. Check the settings in Settings → Email. Those values are written to .env, so the file must be writable by www-data. Restart Horizon after changes (php artisan horizon:terminate), because workers keep the old values.
  4. Read the error in storage/logs/laravel-YYYY-MM-DD.log or in failed jobs (php artisan queue:failed).
  5. Port blocked: many hosting providers block outgoing ports 25 and 465. Use port 587, or the Mailgun API.
  6. Arrives in spam: set up SPF, DKIM and DMARC records for your sending domain with your email provider.

Changes don't show after a deploy ​

SymptomFix
Old design or old JavaScriptChange USER_ASSETS_HASH and run php artisan config:clear (see Cache-busting)
New .env value ignoredphp artisan config:clear, then php artisan horizon:terminate for background jobs
New pages give "route not found"Regenerate the route files and rebuild (see Building assets)
Background jobs behave like the old versionRestart Horizon and the PM2 processes (see Updating → Restart)
PHP changes ignoredsudo systemctl reload php8.3-fpm (clears OPcache)

Still stuck? ​

Collect the last 100 lines of storage/logs/laravel-YYYY-MM-DD.log, the output of pm2w status, and a screenshot of System Monitor, and send them to your support contact.

Owner documentation for the CryptoTech exchange platform.