cortex/docs/troubleshooting.md

Troubleshooting

Docker Is Not Running

Symptom:

Docker is not running or is not reachable.

Fix:

1. Start Docker Desktop.
2. Wait until Docker reports that it is running.
3. Retry the script.

Port Already in Use

Dev ports:

• 5117
• 54329
• 8088

Test ports:

• 5217
• 55439
• 8188

If a port is already used, stop the conflicting process or change the compose file ports.

MCP Client Cannot Connect

Check health:

http://localhost:5117/health

Check MCP URL:

http://localhost:5117/mcp

Check logs:

.\scripts\logs.ps1 -Service app -Follow

Add Tool Fails with Missing Project

This is expected when the project does not exist. Create the project first with CreateProject, then use the category-specific add tool.

Cortex intentionally has no default project.

Search Returns Nothing

Check:

• The item is in the project you searched.
• You did not soft-delete the item.
• You used searchAllProjects = true for global search.
• The embedding service is running.
• Migrations were applied.

Integration Tests Fail from Visual Studio

Start the test stack first:

.\scripts\deploy-test.ps1

Then run tests from Test Explorer.

If you want the script to run tests and leave the stack up:

.\scripts\test-integration.ps1 -KeepRunning

Reset Test State

.\scripts\reset-test.ps1 -Force
.\scripts\deploy-test.ps1

Reset Dev State

.\scripts\reset-db.ps1 -Force
.\scripts\deploy-all.ps1

NuGet Restore Problems

If restore fails:

1. Check network access to https://api.nuget.org/v3/index.json.

2. Check corporate proxy or TLS interception settings.

3. Run restore from a normal PowerShell session:

   dotnet restore Cortex.slnx --configfile NuGet.Config
   

Embedding Container Takes a Long Time

The first start downloads the model and warms the embedding service. Later starts reuse the Docker volume.

The dev and test stacks use separate embedding cache volumes, so the first test run can also take time.