Troubleshooting

"Could not find part of the path" (Windows)

Cause: Windows has a default max path length of 260 characters. AutoSDK generates deeply nested file names that can exceed this.

Solution: Enable long paths in the Windows registry:

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Restart your terminal after applying.

OpenAPI 3.1 Spec Compatibility

Some OpenAPI 3.1 features may need patching. Common fixes in generate.sh:

# Fix nullable types (3.1 uses type arrays)
cat spec.json | jq '
  walk(if type == "object" and .type == ["string", "null"]
       then .type = "string" | .nullable = true
       else . end)
' > patched.json

Spec Parse Errors

AutoSDK ignores parse errors by default (--ignore-openapi-errors). If you need strict validation:

autosdk generate spec.json --ignore-openapi-errors false

Missing Operations

If expected operations aren't generated:

1. Check operationId — Operations without an operationId may be skipped
2. Check deprecated filtering — --exclude-deprecated-operations skips deprecated endpoints
3. Check tag filtering — --includeTags / --excludeTags may filter them out
4. Check operation filtering — --includeOperationIds / --excludeOperationIds

Naming Collisions

AutoSDK automatically resolves naming collisions by appending numeric suffixes (Pet, Pet2, etc.). If this isn't ideal:

1. Update to the latest AutoSDK version
2. Rename schemas in your spec preprocessing:

cat spec.json | jq '
  .components.schemas.PetResponse = .components.schemas.Pet |
  del(.components.schemas.Pet)
' > patched.json

No Base URL / Empty DefaultBaseUrl

If the spec has no servers section:

autosdk generate spec.json --base-url https://api.example.com

Or in MSBuild:

<AutoSDK_BaseUrl>https://api.example.com</AutoSDK_BaseUrl>

Missing Authentication / No Auth Constructors

If the spec doesn't define security schemes:

# HTTP Bearer
autosdk generate spec.json --security-scheme Http:Header:Bearer

# API key in header
autosdk generate spec.json --security-scheme ApiKey:Header:x-api-key

# API key in query
autosdk generate spec.json --security-scheme ApiKey:Query:api_key

# Multiple schemes
autosdk generate spec.json \
  --security-scheme Http:Header:Bearer \
  --security-scheme ApiKey:Header:x-api-key

Large Specs / Slow Generation

AutoSDK uses O(n) algorithms and handles specs with 200k+ lines. To speed things up:

• Use --exclude-deprecated-operations to skip deprecated endpoints
• Use --single-file for fewer file I/O operations
• Filter with --includeOperationIds or --includeTags

Generated Code Won't Compile

1. Verify target framework — Ensure your project targets a compatible framework
2. Check namespace conflicts — SDK-generated types may conflict with your code
3. Clean and regenerate — Delete Generated/ and rerun generation
4. Check polyfills — AutoSDK_GeneratePolyfills=true generates compatibility shims for older frameworks

dotnet tool install Fails

# Clear NuGet cache
dotnet nuget locals all --clear

# Install with explicit source
dotnet tool install --global autosdk.cli --prerelease \
  --add-source https://api.nuget.org/v3/index.json

Ensure you have .NET SDK 8.0 or later installed.