Troubleshooting

Most Scylla problems become easier to diagnose when you identify which layer is failing.

A useful order is:

Application
→ Account / Provider
→ Scope
→ Capability
→ Policy
→ Credential / Connection
→ External service

Avoid changing several layers at once.

Scylla does not start

Check:

1. Windows is fully updated.
2. No installer/update is still pending.
3. WebView2 Runtime is available.
4. The latest official Scylla installer is installed.
5. Endpoint security has not quarantined or blocked a Scylla component.
6. You are launching under the intended Windows user.

If the app previously worked, reinstalling the current official build over the existing installation is a reasonable recovery step before deleting application data.

Provider signs in but Agent cannot run anything

Provider authentication is separate from execution authority.

Check:

• Agent mode;
• active Workspace Scope;
• current project;
• Policy;
• terminal/provider execution settings;
• required Connection;
• Keyring state.

Do not repeatedly reauthenticate the provider if Scylla is clearly blocking the requested operation at a later layer.

Agent cannot see a project folder

Open Manage Scope from FILES.

Confirm the folder is in Workspace Scope and the change has been applied.

A folder existing on disk, appearing under a discovery root, or being a recent project does not make it active automatically.

If more than one project is active, confirm that the correct project is resolved for the operation. Primary is fallback only.

Agent cannot use Knowledge

Open Manage Scope from KNOWLEDGE.

Confirm the folder is in Knowledge Scope.

Knowledge is separate from project files. Adding a folder to Workspace Scope does not automatically add it as Knowledge.

Likewise, a .md file is not Knowledge merely because of its extension.

Git operation is blocked

Check the effective Git Policy.

Typical distinctions include:

status/diff
commit
push
force push
remote-branch changes

Do not assume that because Git authentication works, every operation is allowed.

For Team, check whether the organization enforces the rule through Managed Policy.

Keyring or credential error

If a Connection fails with a credential-related error:

1. Confirm the Keyring is unlocked.
2. Confirm the referenced secret still exists.
3. Confirm the Connection points to the intended secret reference.
4. Confirm the external service still accepts the credential.
5. Test the Connection through Scylla if a connection-test action is available.

Agents receive references and brokered operations, not a vault export. A credential failure should normally surface as an operation error rather than showing the protected value.

Database connection fails

Separate:

network/TLS
authentication
database name/host
Policy
query syntax
database permissions

A successful TCP connection does not mean the database user has permission to perform the requested query.

Use least-privilege accounts and test simple inspection/read operations before trying writes.

SSH connection fails

Check:

• host and port;
• network reachability;
• SSH key/reference;
• username;
• bastion configuration if used;
• server-side authorized keys/permissions;
• Scylla Policy.

Do not paste a private SSH key into Agent chat to work around a failed Connection.

MCP server is connected but tools are unavailable

Treat these separately:

1. Is the MCP server configured and authenticated?
2. Is the connection visible to the active project/provider?
3. Does the current Scylla build discover the required tool?
4. Does Policy allow that class of MCP operation?

Connection health is not the same as tool authority.

Memory says unavailable

Do not read Unavailable as No Memory.

Check:

• current project;
• Scylla Account/Team state;
• project binding;
• local Memory availability;
• Team Memory service state.

A service failure should remain degraded/unavailable rather than pretending the project has zero Memory entries.

Memory appears to belong to the wrong project

Stop using that Memory result and report the issue.

Project identity must be exact. Similar project names must not prefix-match into the same Memory context.

Team features missing

Check:

1. Scylla Account is signed in.
2. Correct organization membership exists.
3. Seat is assigned.
4. Desktop entitlement refreshed.
5. Organization feature is actually configured.

Provider login is irrelevant to Team membership.

Billing changed but seat quantity did not

The browser return from checkout is not authoritative.

Refresh after the billing backend has processed the subscription change.

See Billing.

Team invitation accepted but no license

Invitation acceptance creates membership. Assign a Team seat separately.

See Seat Assignment.

Installation is listed but should no longer be trusted

Use the Team console's installation-revocation action where your role allows it.

Do not remove the entire member solely to revoke one installation.

Agent changes the wrong project

Confirm:

• the target file actually belongs to an active Workspace Scope project;
• chat/project binding;
• Primary project;
• exact project resolution.

Scylla should not use "first project in the list" as a fallback.

UI looks stale after configuration change

For stateful areas such as account, Memory, Policy, or scope:

• save/apply the change;
• switch away/back if the UI has a refresh boundary;
• use the explicit refresh/test action if available;
• restart Scylla only after ordinary runtime refresh fails.

Do not delete configuration just to force a UI refresh.

Collect useful diagnostics

Before reporting a problem, gather:

• Scylla version;
• Windows version;
• affected project name/path, without secrets;
• provider/runtime involved;
• exact operation;
• expected result;
• actual result;
• whether the issue reproduces after restart;
• relevant Policy verdict;
• safe error text;
• screenshots when useful.

Never include:

• passwords;
• API keys;
• private keys;
• raw .env values;
• session tokens;
• full secret-bearing database URLs.

Continue with Contact / Issues.