Troubleshooting · Yuli Code

What to do when something doesn't work: startup, indexing, AI, Claude Code, Git, database and build.

Before anything else, two tools that always help:

Help → Error log… shows the IDE's recent errors.
Help → Report a problem… builds a .zip with what's needed for a diagnosis, without your code or your conversations. Copy summary gives you the text ready to paste.

Ask the agent “what's failing?”. With yuli_health it checks Yuli's problems, run output, tests, terminals and logs in one go.

Installation and startup

Symptom	What to do
Windows shows a warning when you run the installer	Check that you downloaded it from the official source and that the certificate publisher is “Yuli Code”.
The AppImage doesn't open on Linux	Make it executable with `chmod +x`.
The portable version is slow the first time	That's normal: it unpacks the application once per version. After that it starts instantly.
The interface is in another language	Global options → Appearance → Language. See Languages.
You want to measure why startup is slow	Help → Startup performance….

Symptom	What to do
References are missing or navigation is incomplete	Wait for indexing to finish (top bar of the editor).
Lombok or dependencies don't resolve	The project may be in restricted mode. Global options → Security → Trusted projects → Trust.
“No language server for…” warning	Click Install… and authorize the download.
The index looks out of date	Tools → Clear cache… deletes indexes and saved state; Yuli regenerates them.
A JDK, Maven or Gradle is missing	Yuli offers to download it. Configure it in Project → Build, run and debug….

Symptom	What to do
Authentication error in Platform mode	Check the API key in the model configuration and click Test connection.
A local model doesn't answer	Check that the server is running and that the Server URL is correct.
The provider is down	Yuli honors the provider's `retry-after`. Wait, or switch providers.
A background task stopped	It hit its token or cost cap: Raise limit and resume.
The agent team paused	It hit its budget. Raise it in More actions → Agent team.

Symptom	What to do
Yuli can't find the agent	Install it with its official installer and click Detect again.
“Waiting for Claude Code to use Yuli's tools”	Approve the `yuli` server or click Approve now. Check it with `/mcp`.
`/mcp` shows `yuli` with an error	Open the project in Yuli: the tools only work while Yuli is open. `yuli_status` explains why.
The rules didn't change	They load when the session starts: restart it from the agent bar.
Codex says the adapter is missing	Install `codex-acp`: `npm install -g @openai/codex @agentclientprotocol/codex-acp`.
Kiro asks you to update	Yuli needs Kiro CLI 1.28.2 or later.
I don't want Yuli to block anything	Turn off Enforce the rules (“Warn only”). Git and secrets are always protected.

Symptom	Why	What to do
It doesn't commit or push	Git is only enabled by an explicit request.	Ask for it: “commit and push”. Approve each action.
It doesn't create a branch	Branches need their own request.	Ask for the branch explicitly.
It doesn't read a file	It's a secrets file (`.env`, keys, credentials).	That's intentional. Pass along the information without the secret.
It can't write outside the project	The sandbox limits it to the project.	Project → Folder access…
It doesn't run a statement on the database	The connection doesn't grant Super permissions for that class.	Adjust the connection's Agent access.
It doesn't move on to Testing	The measurement is pending or asked for another iteration.	Check the Measurement tab of the Quality panel.
It doesn't finish the turn	Verification isn't green yet.	Look at what's failing in Run, Tests or Problems.

Symptom	What to do
An operation takes too long	When the time limit expires, Retry appears.
Certificate error with an internal server	Mark its certificate as trusted; Yuli remembers the decision per server.
The gate won't let me commit	Read the check that failed (secrets, test integrity, size, protected paths). Fix it or request an exception with an expiry date.
Yuli's hooks weren't installed	Another tool is already set in `core.hooksPath` (for example, husky). Yuli doesn't replace it.

Symptom	What to do
“Connecting to Oracle requires Oracle Instant Client”	Install Instant Client 19c or later and add it to your `PATH`.
Certificate error	Check Trust the server certificate on the connection.
The agent can't see a connection	Its access is set to No access.
An agent query was cut off	It exceeded 45 seconds or its plan estimated too large a scan. Narrow the query.

Symptom	What to do
“Docker is not available”	Start Docker and click Retry.
“kubectl is not configured”	Install `kubectl` and configure a context (kubeconfig).