Troubleshooting

Troubleshooting

Common failure modes and fixes for Cadenza scripts and the SDK packages they pull in.

#:sdk Cadenza@1.* (wildcard / floating version) fails to resolve

You'll see something like:

The NuGetSdkResolver did not resolve this SDK because there was no version specified
in the project or global.json.
Unable to locate the SDK 'Cadenza/1.*'.

Cause: MSBuild SDK references do not support wildcards. This is a different mechanism from PackageReference floating versions — SDK resolution runs before NuGet restore, so the wildcard can't be evaluated. NuGet treats wildcard input as "no version specified" and falls through to the error.

Fix: pin an exact version

#:sdk Cadenza@1.0.15

Bump manually when a new release ships. The latest is on nuget.org/packages/Cadenza.

Alternative: centralize in global.json

Drop a global.json next to (or above) your script:

{
  "msbuild-sdks": {
    "Cadenza": "1.0.15",
    "Cadenza.Worker": "1.0.15",
    "Cadenza.Web": "1.0.15",
    "Cadenza.Mcp": "1.0.15",
    "Cadenza.Agent": "1.0.15"
  }
}

Then scripts omit the version:

#:sdk Cadenza

Useful when several scripts in the same folder need to bump together.

Newly-released version not picked up (stale NuGet cache)

A new version (e.g., 1.0.16) is live on nuget.org but dotnet run keeps resolving an older one:

- Found N versions from nuget.org [nearest version: 1.0.15].
Unable to locate the SDK 'Cadenza/1.0.16'.

Cause: NuGet's HTTP cache holds a stale snapshot of the version list. The SDK resolver consults the same cache.

Clear only the Cadenza entries (no need to nuke the whole cache)

macOS / Linux

# 1. Drop version-list and nupkg entries from the HTTP metadata cache
find "$(dotnet nuget locals http-cache --list | awk '{print $NF}')" \
  \( -name 'list_cadenza*.dat' -o -name 'nupkg_cadenza*.dat' \) \
  -delete

# 2. Remove the extracted packages from the global packages folder
rm -rf ~/.nuget/packages/cadenza \
       ~/.nuget/packages/cadenza.worker \
       ~/.nuget/packages/cadenza.web \
       ~/.nuget/packages/cadenza.mcp \
       ~/.nuget/packages/cadenza.agent

Windows (PowerShell)

# 1. HTTP cache
$httpCache = (dotnet nuget locals http-cache --list).Split(' ')[-1]
Get-ChildItem -Path $httpCache -Recurse -Include 'list_cadenza*.dat','nupkg_cadenza*.dat' |
  Remove-Item -Force

# 2. Global packages folder
Remove-Item "$env:UserProfile\.nuget\packages\cadenza", `
            "$env:UserProfile\.nuget\packages\cadenza.worker", `
            "$env:UserProfile\.nuget\packages\cadenza.web", `
            "$env:UserProfile\.nuget\packages\cadenza.mcp", `
            "$env:UserProfile\.nuget\packages\cadenza.agent" `
            -Recurse -Force -ErrorAction SilentlyContinue

The next dotnet run re-fetches the version index from nuget.org.

Still stuck?

Confirm your NuGet sources include nuget.org rather than only an out-of-date mirror:

dotnet nuget list source

nuget.org should point at https://api.nuget.org/v3/index.json. A custom mirror may lag the public index.

IntelliSense not lighting up in VS Code / Cursor / Kiro

• Confirm the Roslyn LSP is running, not OmniSharp. Open Command Palette → "C#: Open Output" — the first lines should mention Starting Roslyn LSP. If you see OmniSharp, set dotnet.server.useOmnisharp to false in settings.
• On Cursor / Kiro / other forks, the upstream Microsoft C# extension is not available. Install dotnetdev-kr-custom/csharp from Open VSX instead.
• The C# Dev Kit is not required for Cadenza; the base ms-dotnettools.csharp extension (or its community rebuild) is sufficient.
• After installing the extension, fully close and re-open the editor. The LSP doesn't always restart on extension install.

See Editor Setup for the full walkthrough.

dotnet run app.cs says "Could not find file"

The path is relative to the current working directory:

dotnet run ./app.cs              # explicit relative
dotnet run /abs/path/to/app.cs   # absolute

If the folder has exactly one .cs file, plain dotnet run works:

cd path/to/folder
dotnet run

First run is slow

The first dotnet run against a script restores the SDK package plus any #:package references — this can take 10–30 seconds depending on network. Subsequent runs are sub-second because the SDK is now in the global packages folder.

Restore happens per-machine, not per-script — once you've run any Cadenza@1.0.15 script, every other script on the same machine pinned to 1.0.15 reuses the same restore.

macOS: error MSB3552: Resource file "**/*.resx" could not be found

A regression in Cadenza 1.0.0. Fixed in 1.0.1+ — pin @1.0.1 or later (clear cache first per the section above).

Windows: Capture(...) returns garbled CJK / emoji output

Fixed in 1.0.4. Cadenza now decodes captured subprocess output with the host's OEM code page (CP949 on Korean Windows, CP932 on Japanese, etc.) and forces Console.OutputEncoding = UTF-8 on write-back. Upgrade to 1.0.4+.

For the cleanest terminal rendering, run scripts inside Windows Terminal (UTF-8 by default) or run chcp 65001 once in classic cmd.exe / conhost.

My MCP server starts but Claude / Cursor never sees the tools

• Don't write to stdout — WriteLine is intentionally not exposed in Cadenza.Mcp because it corrupts the JSON-RPC framing. If you have any Console.WriteLine from a library or shim, route it through Log.* instead.

• In the client config, use an absolute path to the .cs file:

  {
    "mcpServers": {
      "files": {
        "command": "dotnet",
        "args": ["run", "/absolute/path/to/mcp-files.cs"]
      }
    }
  }

• Check the client's MCP log — Claude Desktop's log is under ~/Library/Logs/Claude/ (macOS) / %APPDATA%\Claude\logs\ (Windows).

My Cadenza.Web / Cadenza.Agent container starts, but I can't reach it

You're bound to localhost. Inside a container, that's not reachable from the host.

Cadenza.Web — set ASPNETCORE_URLS:

docker run -e ASPNETCORE_URLS=http://0.0.0.0:8080 -p 8080:8080 my-image

Or bake it into the image:

#:property ContainerEnvironmentVariables=ASPNETCORE_URLS=http://0.0.0.0:8080;ASPNETCORE_HTTP_PORTS=8080

Cadenza.Agent — set the property in the script:

Agent.HostName = "0.0.0.0";
Agent.Port     = 8080;
await Run();

See Deployment Container.

Worker host has not been started when calling Worker.Config<T>(...) or Worker.Service<T>()

These access the Generic Host's services and require the host to be built — call them inside the Run callback, not at the top of the script:

await Run(async (ct) =>
{
    var endpoint = Worker.Config<string>("Api:Endpoint");
    // …
});

See Cadenza Worker → "Configuration".

Cadenza.Agent fails to start with "Configure an LLM with UseOllama / UseOpenAi / …"

You called Run() (or ChatLoop() / Reply(...)) without picking a backend. Add one of:

UseOllama("llama3.2");
UseOpenAi("gpt-4o-mini");
UseAnthropic("claude-sonnet-4-5");
UseAzureOpenAi("https://your.openai.azure.com", "deployment-name");
UseChatClient(yourCustomChatClient);

before Run(). See Cadenza Agent → "Backends".

See also

• Installation
• Editor Setup
• Deployment Container
• Spec — formal reference