Troubleshooting & FAQ

Owner-level problems — installing, the scheduler, and keeping the app itself reachable. For anything about connecting a channel, the knowledge base, the AI provider not answering, or a subscriber's plan, see the companion Using Threadline guide's own Troubleshooting page — most day-to-day symptoms live there, even for a solo, non-SaaS install.

Installation & access

The installer appeared again on my live site

Threadline shows the installer whenever the file storage/app/public/installed is missing — usually because the storage/ folder was replaced during an upload or server move. Don't run the installer again: it drops your existing tables. Recreate the file instead (it can be empty). See Install on Shared Hosting.

System → Cron & Health shows an amber warning

Your cron job isn't running — nothing in Threadline that depends on scheduled jobs (sending messages, processing uploaded documents, retrying failed AI calls) happens until it is. See Cron Setup.

An uploaded logo or image does not show

Uploaded files are served through a link named public/storage. If it is missing, create it with php artisan storage:link (as the website's user, in the Threadline folder). If PHP's symlink function is switched off on your server, enable it first, or create the link over SSH with ln -s /path/to/threadline/storage/app/public /path/to/threadline/public/storage.

The cron job runs, but nothing scheduled happens

The PHP function proc_open is probably switched off in the disable_functions list of your PHP version (aaPanel does this by default). The scheduler then reports each task as done without running it. System → Cron & Health lists the requirement. On aaPanel see Allow the PHP functions Threadline needs.

Messages are not sent and the queue worker keeps stopping

On a VPS the worker needs pcntl_signal and pcntl_alarm. If your PHP lists them under disable_functions, the worker stops the moment it starts and the supervisor restarts it again and again. Remove them from that list. On aaPanel see Step 4.

AI providers & Knowledge Bases

A Knowledge Base shows "Frozen"

The API key its own original embedding provider needs is missing or was removed — not a settings mismatch. Existing content keeps answering questions normally on every channel; only adding new content is blocked. Add (or restore) that provider's key under Configuration → Integrations → AI to unfreeze it. See Changing your Chat or Embedding provider/model later for the full explanation — changing the platform's active embedding model on its own never freezes an existing Knowledge Base.

Owner area & billing

A customer paid but their plan did not start

The gateway's webhook did not reach Threadline, or its secret is wrong. Open the gateway's dashboard and look for failed deliveries, then check the webhook address and secret on Payment Gateways. Until it is fixed you can start their plan yourself with Assign plan.

Customers say they never get emails

Look for the red banner on the Owner dashboard. If mail is not configured, add a server under Mail & Email Templates and press Send test email.

I cannot create a paid plan

No payment gateway is switched on. A paid plan's price is created on every enabled gateway, so enable one first. See Payment Gateways.

A client can still not create anything new

Their subscription is probably past due or they reached a plan limit. Open the client and check Usage against the plan and the subscription status. See Subscriptions & Payments.

The "Connect with Meta" button does not show

The switch on the Meta app page is off, the app is not fully configured, or Meta has not approved it yet. See Meta App & One-click Connect.

A teammate cannot see a page

Their role does not include that permission. Edit the role under Roles, Staff & Audit Log.

Something else is broken

If the main app itself won't load at all, the Maintenance page (in the Owner's sidebar) is deliberately built to keep working independently (it's a plain page, not part of the main React app) — it's reachable even if a bad update corrupts the compiled frontend assets, and includes backup, restore, and update tools. Contact support through your purchase page if you're still stuck after checking there.