Errors & Troubleshooting

Guide to common Soxom errors and how to resolve them.

Configuration Errors

SOXOM001: Config file not found

Error: SOXOM001 - Configuration file not found
  Path: ./soxom.yaml

Cause: Soxom cannot find soxom.yaml at the root of the Config Repository.

Solution:

1. Ensure soxom.yaml is committed to the root of the Config Repository (not a subdirectory).
2. Push the fix to the Config Repository — the build retries automatically. To re-run an existing build, click Retry in the Builds view or POST /api/v1/projects/:projectId/sdk-targets/:id/sdk-builds/:buildId/retry.

---

SOXOM002: Invalid config syntax

Error: SOXOM002 - Invalid YAML syntax in soxom.yaml
  Line 15: unexpected key "sdks"

Cause: YAML syntax error or invalid key.

Solution:

1. Check YAML syntax (indentation, colons)
2. Verify key names match reference
3. Detailed errors appear in the Builds view of the Soxom dashboard

---

SOXOM003: Missing required field

Error: SOXOM003 - Missing required field
  Field: sdk.name

Cause: Required configuration field is missing.

Solution: Add the required field to your config:

sdk:
  name: my-sdk    # Required
  version: 1.0.0  # Required

---

SOXOM004: Invalid target language

Error: SOXOM004 - Invalid target language
  Target: "ruby"
  Valid targets: typescript, python, go, java

Cause: Specified target language is not supported.

Solution: Use a supported language:

targets:
  - typescript
  - python
  - go
  - java

---

OpenAPI Spec Errors

SOXOM101: Spec file not found

Error: SOXOM101 - OpenAPI spec not found
  Path: ./openapi.yaml

Cause: Cannot find the OpenAPI specification file.

Solution:

1. Verify the path in spec.path
2. Check file exists and is readable

---

SOXOM102: Invalid OpenAPI version

Error: SOXOM102 - Unsupported OpenAPI version
  Found: 2.0 (Swagger)
  Supported: 3.0, 3.1

Cause: Soxom only supports OpenAPI 3.0 and 3.1.

Solution: Convert your Swagger 2.0 spec to OpenAPI 3.x:

• Use Swagger Editor
• Use swagger2openapi CLI tool

---

SOXOM103: Invalid spec syntax

Error: SOXOM103 - Invalid OpenAPI syntax
  Line 42: invalid $ref format

Cause: OpenAPI spec has syntax or structure errors.

Solution:

1. Validate spec with Swagger Editor
2. Check $ref paths are correct
3. Ensure all required fields present

---

SOXOM104: Unresolved reference

Error: SOXOM104 - Unresolved $ref
  Reference: #/components/schemas/User
  Location: paths./users.get.responses.200

Cause: A $ref points to a schema that doesn’t exist.

Solution:

1. Check the schema name is correct
2. Ensure schema is defined in components/schemas
3. Verify path is correct (case-sensitive)

---

SOXOM105: Circular reference

Error: SOXOM105 - Circular reference detected
  Path: User → UserProfile → User

Cause: Schemas reference each other in a cycle.

Solution: Break the cycle using a different schema design:

# Instead of direct circular reference
User:
  properties:
    profile:
      $ref: '#/components/schemas/UserProfile'

UserProfile:
  properties:
    user:
      $ref: '#/components/schemas/User'  # Circular!

# Use ID reference instead
UserProfile:
  properties:
    user_id:
      type: string  # Reference by ID, not embedded

---

Generation Errors

SOXOM201: Resource not found

Error: SOXOM201 - Operation not found
  Resource: users
  Method: list
  Operation: get /users

Cause: Configured operation doesn’t exist in spec.

Solution:

1. Verify the path and HTTP method
2. Check for typos in soxom.yaml
3. Ensure operation exists in OpenAPI spec

---

SOXOM202: Model not found

Error: SOXOM202 - Schema not found
  Resource: users
  Model: UserCreate

Cause: Referenced model doesn’t exist in spec.

Solution:

1. Check schema name in components/schemas
2. Names are case-sensitive
3. Remove from models list if not needed

---

SOXOM203: Naming conflict

Error: SOXOM203 - Naming conflict
  Name: "Status" used by multiple schemas
  Schemas: UserStatus, OrderStatus

Cause: Multiple schemas generate the same type name.

Solution: Rename schemas to be unique:

# Before
UserStatus:
  type: string
OrderStatus:
  type: string

# Both become "Status" in some languages

---

SOXOM204: Invalid method mapping

Error: SOXOM204 - Invalid method mapping
  Method: list: "get/users"
  Expected format: "<http-method> <path>"

Cause: Method mapping syntax is incorrect.

Solution: Use correct format with space separator:

methods:
  list: get /users      # Correct
  create: post /users   # Correct

---

Runtime Errors (Generated SDK)

Connection Errors

Error: ConnectionError - Unable to connect
  URL: https://api.example.com

Solutions:

1. Check network connectivity
2. Verify API URL is correct
3. Check firewall/proxy settings

---

Authentication Errors

Error: AuthenticationError - 401 Unauthorized

Solutions:

1. Verify token/credentials are correct
2. Check token hasn’t expired
3. Ensure correct auth method configured

---

Rate Limit Errors

Error: RateLimitError - 429 Too Many Requests
  Retry-After: 60

Solutions:

1. SDK will auto-retry if configured
2. Reduce request frequency
3. Implement backoff in your code

---

Troubleshooting Guide

SDK not generating expected methods

Tip

Soxom surfaces warnings about missing operations in the Builds view of the dashboard. Strict-mode behavior is the default — every build flags unresolved or skipped operations.

1. Check resources mapping in soxom.yaml
2. Verify operations exist in OpenAPI spec
3. Ensure operations aren’t marked with x-soxom-ignore

Types not matching expected

1. Check OpenAPI schema definitions
2. Review naming conventions
3. Verify oneOf/allOf are used correctly

Pagination not working

1. Verify x-soxom-pagination extension
2. Check response structure matches config
3. Ensure has_more or total field exists

Retries not happening

1. Check retry configuration
2. Verify status code is in retry_on list
3. Check operation doesn’t have x-soxom-retries: enabled: false

Verbose Debugging

Open the Builds view in the dashboard and expand the build to see full generator logs, including resolved spec paths, per-operation diagnostics, and stack traces for any failures. If a build is in a stuck state, click Retry to re-run it; for programmatic access, POST /api/v1/projects/:projectId/sdk-targets/:id/sdk-builds/trigger queues a fresh build against the latest Config Repository commit.

---

Getting Help

Check Documentation

• Configuration Reference
• OpenAPI Extensions
• REST API Reference

Report Issues

If you encounter a bug:

1. Copy the build ID and full log from the Builds view
2. Include the full error message
3. Include soxom.yaml (remove secrets)
4. Include relevant parts of the OpenAPI spec

Report at: GitHub Issues