> This page is for SDK, version Legacy.
> For other versions, use one of these documentation indexes:
> - Current (default): https://buildwithfern.com/learn/sdks/current/llms.txt
> - Legacy: https://buildwithfern.com/learn/sdks/legacy/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Go configuration

> Configuration options for the Fern Go SDK.

> **You're viewing the legacy SDK docs**
>
> These pages cover SDK generation configured with `generators.yml`. New projects use `sdk-config.yml`, so see [the Current version of this page](/learn/sdks/generators/go/configuration) for up-to-date guidance. To move an existing project, follow the [SDK Config migration guide](/learn/sdks/legacy/generators/migration-guides/sdk-config), which walks through `fern sdk migrate`, and review the [`sdk-config.yml` reference](/learn/sdks/reference/sdk-config).

You can customize the behavior of the Go SDK generator in `generators.yml`:

**`generators.yml`**

```yaml {6-7} title="generators.yml"
groups:
  go-sdk:
    generators:
      - name: fern-go-sdk
        version: 1.70.7
        config:
          packageName: acme
        output:
          location: local-file-system
          path: ../generated/go
```

**`alwaysSendRequiredProperties`** `boolean` — default: true

When enabled, ensures that all required properties are always included in API requests, even if they have default values or are otherwise optional in the implementation.

---

**`auto-generate-idempotency-key`** `boolean | object` — default: false

Overrides the API-wide [`api.settings.auto-generate-idempotency-key`](/learn/sdks/legacy/reference/generators-yml#settings) for this SDK. Set `true` to attach an [idempotency-key header](/learn/sdks/legacy/deep-dives/idempotency#auto-generate-idempotency-keys) to eligible requests (`POST` and `PUT` by default) unless the caller provides one, or `false` to opt this SDK out when auto-generation is enabled API-wide. Pass an object to customize `header-name` and `methods`.

---

**`clientConstructorName`** `string`

Customizes the name of the client constructor function. This allows you to specify a custom name for the function that users will call to create a new instance of the client.

---

**`clientName`** `string`

Specifies the name of the generated client struct. This determines the primary client type name that users will interact with in the generated Go SDK.

---

**`exportedClientName`** `string`

Sets the name of the exported client that will be used in code snippets and documentation examples. This is useful for customizing how the client appears in generated documentation.

---

**`maxRetries`** `number`

The default number of retries for failed requests. When not set, the generated SDK uses its own built-in default. SDK users can still override this per-request via request options.

---

**`offsetSemantics`** `'item-index' | 'page-index'`

Controls how the offset parameter is interpreted for [auto-paginated](/learn/sdks/legacy/deep-dives/auto-pagination) endpoints.

* `item-index`: The offset counts individual items (e.g., offset 20 skips the first 20 items).
* `page-index`: The offset counts pages (e.g., offset 3 skips to page 3).

---

**`omitFernHeaders`** `boolean` — default: false

When enabled, the generated SDK omits the `X-Fern-Language`, `X-Fern-SDK-Name`, and `X-Fern-SDK-Version` headers from HTTP requests.

---

**`includePlatformHeaders`** `boolean` — default: false

When enabled, the generated SDK sends a single structured `User-Agent` header of the form `{sdkName}/{version} ({os}; {arch}) {runtime}/{runtimeVersion}` (for example, `my-sdk/0.0.1 (linux; x86_64) Go/1.22.0`), carrying SDK, operating system, architecture, and runtime information in place of the default `User-Agent` and discrete platform headers. A configured [`user-agent`](#user-agent) template supplies the leading product token. If `omitFernHeaders` is enabled, no `User-Agent` or platform headers are sent and this option has no effect.

---

**`allowUserAgentAppInfo`** `boolean` — default: false

When enabled, the generated SDK exposes `option.WithUserAgentAppInfo(name, version, comment)`, which appends a `{name}/{version} ({comment})` [product token](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) to the `User-Agent` header so an application built on the SDK can identify itself to the API. The application passes a required name plus an optional version and comment; `""` drops that part of the token. An explicit `User-Agent` header takes precedence, and [`omitFernHeaders`](#omitfernheaders) suppresses the header entirely.

```go
option.WithUserAgentAppInfo("partner-app", "3.1.0", "+https://partner.example")
// User-Agent: my-sdk/0.0.1 (linux; x86_64) Go/1.22.0 partner-app/3.1.0 (+https://partner.example)
```

---

**`enableRequestBodyPagination`** `boolean` — default: false

Generates [auto-pagination](/learn/sdks/legacy/deep-dives/auto-pagination) for endpoints whose cursor or offset page property is a top-level request body property (for example, `cursor: $request.cursor`). The generated pager advances the page by setting the field on the request object instead of on the query string. This defaults to `false` because enabling it changes the affected methods' return types from a response to a pager. Nested body page properties (for example, `cursor: $request.pagination.cursor`) still generate a plain, non-paginated method unless [`enableNestedRequestBodyPagination`](#enablenestedrequestbodypagination) is also enabled.

---

**`enableNestedRequestBodyPagination`** `boolean` — default: false

Extends [`enableRequestBodyPagination`](#enablerequestbodypagination) to endpoints whose page property lives inside a nested request body object (for example, `offset: $request.options.offset` or `cursor: $request.options.pagination.cursor`). The generated pager copies the request and each optional intermediate object when advancing, so it works whether the caller sets the nested object or leaves it `nil`. Requires `enableRequestBodyPagination: true`, and defaults to `false` because enabling it changes the affected methods' return types from a response to a pager.

```yaml
- name: fernapi/fern-go-sdk
  config:
    enableRequestBodyPagination: true
    enableNestedRequestBodyPagination: true
```

---

**`enableWireTests`** `boolean` — default: true

Generates [mock server (wire) tests](/learn/sdks/legacy/deep-dives/testing#mock-server-tests) to verify that the SDK sends the correct HTTP requests and correctly handles responses per the API spec. When enabled, Docker is required as a runtime dependency to run the generated tests.

---

**`importPath`** `string`

Use this option if you plan to depend on the generated Go SDK from within your project, and **not** depend on it as a separate, published Go module.

> **Note**
>
> If you plan to to distribute the generated Go SDK as a separate, published Go module, use the `module` configuration option instead.

You can generate the Go SDK code into a `gen/go/api` package with the following `generators.yml`
configuration:

```yaml {7-8}
default-group: local
groups:
  local:
    generators:
      - name: fern-go-sdk
        version: 0.13.0
        config:
          importPath: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>/generated/go
        output:
          location: local-file-system
          path: ../generated/go
```

> **Info**
>
> You must update the `<YOUR_ORGANIZATION>` and `<YOUR_REPOSITORY>` placeholders
> with the relevant elements in your `go.mod` path. In this case, the generated Go SDK uses the same `go.mod` path used by the rest of your Go module.

---

**`includeLegacyClientOptions`** `boolean`

When enabled, includes legacy client options for backward compatibility with older versions of the SDK. This is useful for maintaining compatibility when upgrading SDK versions.

---

**`inlineFileProperties`** `boolean` — default: true

Controls whether file upload properties are generated as inline request properties instead of separate parameters. When enabled, file upload fields become part of the request struct rather than being passed as individual function parameters.

---

**`inlinePathParameters`** `boolean` — default: true

When enabled, path parameters are inlined into request types rather than being passed as separate function parameters. This creates a more unified request structure where path parameters are included in the request object.

---

**`module`** `object`

Use this option if you plan to distribute the generated Go SDK as a separate, published Go module.

> **Note**
>
> If you only plan to use the generated SDK within your own Go module, use the `importPath` configuration option instead.

You can generate the Go SDK code into a separate module (defined with its own `go.mod`)
with the following `generators.yml` configuration:

```yaml {7-9}
default-group: local
groups:
  local:
    generators:
      - name: fern-go-sdk
        version: 0.13.0
        config:
          module:
            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
        output:
          location: local-file-system
          path: ../generated/go
```

This configuration will generate a `go.mod` alongside the rest of the Go SDK code at the target output
location. With this, `import` statements within the generated Go SDK are all resolved from the configured
module path.

By default, the generated `go.mod` will be set to `1.13`. You can override this behavior by specifying
the `version` key:

```yaml {10}
default-group: local
groups:
  local:
    generators:
      - name: fern-go-sdk
        version: 0.13.0
        config:
          module:
            path: github.com/<YOUR_ORGANIZATION>/<YOUR_REPOSITORY>
            version: "1.19"
        output:
          location: local-file-system
          path: ../generated/go
```

If you want to depend on the generated Go SDK locally (without distributing it as a separate Go module),
and you use the `module` configuration option, you will need to modify your project's top-level `go.mod` to include a [`replace`](https://go.dev/doc/modules/gomod-ref#replace) statement:

```go
module github.com/your/module

require "github.com/your/sdk" v0.0.0
replace "github.com/your/sdk" v0.0.0 => "path/to/generated/sdk"
```

---

**`packageName`** `string`

Specifies the package name for the generated Go code. This determines the package declaration that will appear at the top of generated Go files and affects how users import the SDK.

---

**`respectOptionalRequestBody`** `boolean` — default: false

Lets callers omit the request body on endpoints with an optional request body. A request wrapper with a `nil` body sends no body and no `Content-Type` header, instead of the JSON literal `null`. Enable this when your API treats a missing body differently from a `null` one.

Only applies to request bodies declared as a single named type. Required bodies and inlined request properties are unaffected.

---

**`serverUrlVariables`** `boolean` — default: true

Controls whether the generated SDK emits [server URL variable](/learn/sdks/legacy/deep-dives/server-url-templating) client options and construction-time base-URL template interpolation. Set to `false` to disable both, falling back to the base-URL behavior from before server URL templating.

---

**`union`** `'v0' | 'v1'` — default: v1

Controls the union type generation strategy. Use 'v0' for the legacy union implementation or 'v1' for the newer, more robust union handling approach that provides better type safety and discriminated union support.

---

**`useReaderForBytesRequest`** `boolean` — default: true

When enabled, uses `io.Reader` interface for handling byte request bodies instead of byte slices. This is more memory-efficient for large payloads and follows Go best practices for streaming data.

---

**`user-agent`** `string` — default: \{packageName}/\{version}

Sets a custom `User-Agent` header template for requests sent by the generated SDK. The template is resolved at generation time and supports the `{packageName}`, `{version}`, `{language}`, `{generatorVersion}`, `{organization}`, and `{apiName}` placeholders.

**`generators.yml`**

```yaml title="generators.yml"
config:
  user-agent: "plantstore-go-sdk/{version}"
```

This sends `User-Agent: plantstore-go-sdk/0.1.0`. With [`includePlatformHeaders`](#includeplatformheaders) enabled, the resolved value leads the structured header: `User-Agent: plantstore-go-sdk/0.1.0 (linux; x86_64) Go/1.22.0`. A value that doesn't end in a version, such as `plantstore/sdk-go`, is used as-is. The [`allowUserAgentAppInfo`](#allowuseragentappinfo) token is appended after either form.

---