Troubleshooting

No code generated

Symptoms: Build succeeds but no client classes are generated.

Solutions:

1. Ensure API spec class is annotated with @GenerateApi and extends ApiSpec
2. Ensure baseUrl is overridden
3. Check that request classes are in the scan packages (default: <api-package>.models)
4. Verify request classes have @Serializable and HTTP method annotations
5. Check KSP is properly configured in build.gradle.kts

Compilation errors in generated code

Symptoms: Generated code has import or type errors.

Solutions:

1. Ensure all response types are @Serializable
2. Add required Ktor dependencies
3. Check that kotlinx.serialization plugin is applied

Path variable mismatch

Symptoms: Error about path variable not matching.

Solutions:

1. Ensure path variable names match property names exactly
2. Check for typos in {variableName} syntax
3. Verify @Path annotation is present on the property

Query parameters not working

Symptoms: Query parameters ignored or cause errors.

Solutions:

1. Add @Transient annotation alongside @Query
2. Make query parameters nullable
3. Only use on GET or DELETE requests

Authentication not applied

Symptoms: Requests fail with 401 Unauthorized.

Solutions:

1. Verify @Auth annotation is on the request class
2. Provide credentials via context parameters
3. For CUSTOM auth, provide the HttpRequestBuilder.() -> Unit lambda via a context parameter

Build performance

Symptoms: Slow incremental builds.

Solutions:

1. Use KSP incremental processing (enabled by default)
2. Minimize changes to API spec files
3. Consider splitting large APIs into multiple specs