Troubleshooting

Do this first

Whatever the problem, read runtime.log in the site root.

That means the runtime.log in the root, not the one under runtime/log/. The real cause of almost every problem is written there.

With DEBUG=false, any uncaught exception is rendered as the 404 page and returned with HTTP 500 — the page gives you nothing. The real cause exists only in runtime.log.

Installation and access

Only the home page loads; every link 404s URL rewriting is not configured. See rewrite rules.

Blank page / 500 Usually a missing bcmath extension. Every money calculation depends on it, and without it the program throws a fatal error. See installation overview.

The installer says a directory is not writableconfig, runtime, kernel/Install and assets/cache must be writable. In aaPanel, select the site root under Files → Permission and set the owner to www.

The Docker container is running but the browser cannot connect The port mapping is reversed. In -p 8080:80 the left side is the host port; the right side is always 80. On a cloud server, also open the port in the security group.

Data disappeared after a Docker upgrade-v acg_data:/data was missing. See Docker installation.

After migrating

If the site does not work on the new server, check in order:

1. config/database.php — still pointing at the old database?
2. If the old site used Redis for sessions, install it here too or switch PHP's session storage back to files
3. Are all PHP extensions installed — especially bcmath?
4. Directory permissions and URL rewriting both need configuring again

See upgrading and migrating.

Accounts and sign-in

Every member was signed out after upgrading to 3.8.1 Expected. 3.8.1 rebuilt member sign-in credentials for security; each member just signs in once more. See account & sign-in security.

The sign-in page has no "Sign in with a passkey" button Passkeys need the site opened at https://your-domain — an IP address or plain http will not do — and a system browser. The built-in browsers of WeChat, QQ and Alipay are not supported.

The admin panel keeps locking itself That is the idle lock screen added in 3.8.1, which locks after 15 minutes without activity by default. Raise Admin Idle Lock under Site settings → Security, or set it to 0 to turn it off.

Orders and payments

A buyer paid but received nothing

1. Search Orders by order number or contact and confirm the order exists
2. Check its state — still "Unpaid" means the payment callback never arrived
3. Callbacks usually fail because the callback URL at the provider is wrong, or a CDN firewall is blocking it
4. For CDN problems, use a custom payment callback domain — see site settings

Stock clearly exists but the storefront says sold out When a product has variants or SKUs, stock is counted per combination. One combination with no keys is sold out even if the total looks healthy. Keys may also be locked. See card keys and stock.

The buyer chose yearly and got a monthly key The keys were imported under the wrong variant.

A product shows as costing 0 If the member price is left blank, logged-in users may be able to take it for free. Fill both prices in. See payment setup.

Sub-stores

Subdomain will not load Three things are needed, all of them: main domain and DNS CNAME configured in the panel, a * wildcard record at your DNS provider, and *.your-domain bound on the server. The last one is the one people miss.

Custom domain will not load No default site is configured on the server. See sub-stores.

Store sharing

Adding the store fails Wrong address, merchant ID or key — or sharing is not enabled on their side.

Customer orders error out and nothing is delivered Your balance upstream has run out. Shared orders are paid from your balance on the upstream store.

If the error is about fund verification or the integration whitelist, go by the message:

• "该账号已开启资金二次验证，必须先登记对接白名单 IP…" (fund verification is on, so an IP must be on the integration whitelist first): the upstream runs 3.8.2 or later, your upstream account has fund operation verification on and its whitelist is still empty. Add your server's IP to the integration IP whitelist in the upstream user centre
• "调用方 IP 不在该账号的对接白名单内…" (the caller's IP is not on this account's integration whitelist): the upstream runs 3.8.2 or later, your upstream account has a whitelist, and your server's IP is not on it. Add it in the same way
• "该账号已开启资金二次验证，无法通过对接接口消费余额" (the balance cannot be spent through the integration API): the upstream runs 3.8.1, which has no whitelist. Turn fund operation verification off on that account, or ask the upstream to upgrade to 3.8.2

The whitelist is on the Integration whitelist page in the default theme, or on the Two-step verification page in other themes. Refused IPs are listed under Recently refused below the whitelist, ready to add with one click.

The product list comes back empty Their products do not have "API access" enabled.

Plugins and themes

Installed a plugin and nothing happened You still have to enable it under Plugins.

Added a new hook file and it does not fire The hook registry is a compiled cache. Disable and re-enable the plugin to rebuild it.

The site renders incorrectly after switching themes Clear the template cache by deleting the contents of runtime/view/compile.

Never delete runtime/config — that is the configuration cache and removing it breaks the site.

How to ask for help

Nobody can diagnose your problem from a one-line description. Before asking, have these ready:

1. The contents of runtime.log — it is in the site root after any error
2. What you did immediately before the problem appeared
3. Screenshots of anything relevant

Preparing these is the fastest route to an answer. You can of course describe the problem in a sentence and hope someone helps, but it will not save you time — it just turns into a long back-and-forth.

Where to ask

• Telegram: https://t.me/mcyofficial
• QQ group: 868709021