Support and troubleshooting

What to do when something doesn't work in a fleet deploy. Ordered roughly by frequency.

For the always-current host list and log paths, see Reference → Network endpoints and Reference → Log locations.

App is slow on launch / chat hangs

Symptom: EasyCC takes 15+ seconds to show the window, or chat shows Concocting… for several minutes before timing out.

Most common cause: A cloud connector or MCP server is unresponsive during startup. Each unresponsive server can add 60–180 seconds.

Fix:

Settings → Connectors → Disable all (in EasyCC on the affected device).
Re-enable connectors one by one to find the offender.
At scale, push a managed policy that disables the bad connector fleet-wide.

Symptom: Sign-in error before the user can enter their email.

Likely causes:

Device can't reach <your-supabase-project>.supabase.co.
Device can't reach api.anthropic.com (some sign-in flows pre-check this).
For Microsoft sign-in: tenant restrictions are blocking EasyCC (run admin consent — see Configuration → Microsoft Entra setup).
A corporate proxy is doing TLS interception and EasyCC can't verify the cert chain.

Fix: confirm allowlist + proxy config against Reference → Network endpoints.

"WebView2 not found" on Windows

Symptom: Installer fails, or app fails to launch with a missing-runtime error.

Cause: WebView2 isn't installed (pre-installed on most Windows 10/11 but not all SKUs).

Fix:

winget install Microsoft.EdgeWebView2Runtime

Or push WebView2 via your MDM as a prerequisite app.

"App is damaged" on macOS

Symptom: "EasyCC.app is damaged and can't be opened" on first launch (common after a direct download to Apple Silicon).

Cause: Apple's quarantine attribute on apps installed outside the App Store.

Fix:

xattr -cr /Applications/EasyCC.app

The .dmg drag-to-Applications flow can trigger this on some Apple Silicon Macs. The MDM-ready .pkg path (on the roadmap) avoids this entirely.

A managed policy isn't taking effect

Symptom: You pushed a policy but Settings → Advanced doesn't show locked fields.

Likely causes (in order of frequency):

Cause	Check
EasyCC wasn't restarted	Managed policy is read on launch. Quit fully and relaunch.
Wrong registry hive on Windows	Use `HKLM`, not `HKCU`. EasyCC reads from `HKLM\Software\Policies\EasyCC`.
Typo in field name	Names are `snake_case`; case- and spelling-sensitive.
Wrong value type	Booleans are `DWord` 0/1, not `String`. See Configuration for the type cheat sheet.
User-side AppConfig still wins	If the field's kind is `default` (not `enforced`), the user's setting overrides. Push as `enforced` if you need the lock.

Verify:

Get-ItemProperty 'HKLM:\Software\Policies\EasyCC' | Format-List

sudo defaults read /Library/Managed\ Preferences/com.easycc.app

If the keys are visible but EasyCC's UI doesn't reflect them, search the EasyCC log for easycc::managed entries — that subsystem logs every key it reads on launch, plus warnings for unknown keys or malformed values.

A bundle isn't applying on first launch

Symptom: EasyCC starts as vanilla despite a bundle being deployed.

Likely causes:

Cause	Check
Bundle is in the wrong location	Windows: `%PROGRAMDATA%\EasyCC\bootstrap.json`. macOS: `/Library/Application Support/EasyCC/bootstrap.json`.
Bundle JSON is malformed	Validate with `jq . bootstrap.json` (or any JSON validator).
File permissions block read	Bundle must be readable by the user running EasyCC.
`bundleId` matches a previous apply	Each `bundleId` applies once per device. Increment the version or use a new `bundleId` to force re-apply. See Bundles → Re-apply and idempotency.

Search the EasyCC log for easycc::bundle entries — discovery + apply each log their outcome.

"Couldn't read secret from keychain"

Symptom: EasyCC logs couldn't read secret from keychain: <key> and fails the corresponding operation.

Likely causes:

Cause	Check
Secret slot is empty	Run `cmdkey /list` (Windows) or `security find-generic-password -s com.easycc.app -a <slot>` (macOS) on the device.
Slot name doesn't match what EasyCC expects	EasyCC reads canonical slots like `auth_claude_api_key`. See Secrets for the full list.
Push script ran but failed silently	Check your MDM's script run history. On Windows, the `/pass:` argument needs to be a single token (escape spaces).
Secret was pushed to user keychain instead of system keychain on macOS	Use `/Library/Keychains/System.keychain` so any user on the device can read it.

Update repeatedly fails

Symptom: Update banner keeps reappearing; install fails or stalls.

Likely causes:

Cause	Check
Disk full	`Get-PSDrive C` on Windows; `df -h` on macOS. EasyCC needs ~200 MB free for the update plus working space.
Anti-virus quarantines the binary	Check the AV quarantine log for `EasyCC` entries. Allowlist the install path.
Update endpoint unreachable	Test the URL from the device. If using a self-hosted mirror, verify the manifest URL is reachable.
Manifest signature mismatch	If you're mirroring, you may have edited a field other than `platforms.*.url`. Signatures verify archive contents — restore the manifest byte-for-byte from the source.

For force-install policies, see Deploy → Deferral and force install.

App crashes on launch

Symptom: Process starts and immediately exits.

Likely causes:

Corrupted config (config.json malformed)
WebView2 issue on Windows
A bundle's apply step is crashing on bad input

Fix:

Pull the most recent log file and search for panic or FATAL.
Try launching with --clear-caches --reset-window-layout.
If a bundle is involved, temporarily move the bundle file out of discovery paths and relaunch.

Pulling a diagnostic bundle

When you need to send something to support, the diagnostic bundle is the right thing.

In EasyCC: Settings → About → Pull diagnostic bundle. EasyCC writes a .zip containing:

Recent logs (last 30 days)
App version, OS version, hardware summary
Managed policy snapshot (what EasyCC sees on this launch)
Bundle apply state (what was applied, when)
Anonymized config (no chat content, no file content, no credentials)
Crash dumps if any

The bundle never includes chat content, file content, credentials, or anything from the keychain.

For automation: the same bundle can be produced from the CLI:

& "$env:LOCALAPPDATA\EasyCC\EasyCC.exe" --diagnostic-bundle "$env:USERPROFILE\Desktop\easycc-diag.zip"

/Applications/EasyCC.app/Contents/MacOS/EasyCC --diagnostic-bundle ~/Desktop/easycc-diag.zip

Where to escalate

Need	Where
Bug report or feature request	github.com/EasyCCapp/EasyCC/issues
Security disclosure	Email `security@easycc.app` (see SECURITY.md)
Enterprise support (your service-provider partner)	Your partner's support channel — they have a direct line
Direct EasyCC support	Contact your EasyCC representative; attach the diagnostic bundle

For high-severity production incidents (whole fleet broken), contact your EasyCC representative directly with the diagnostic bundle attached — don't file a public issue.

Support and troubleshooting

On this page