microsoft / microsoft/kiota

Fails to resolve local relative $ref references to external files on macOS (zsh) and official Kiota Docker container

Open
#7,319 0 comments 0 reactions 0 assignees View on GitHub
status:waiting-for-triage type:bug
Dominant language
C#
Stars
3.8k
Forks
333
Avg merge
16h 29m
Merged PRs (30d)
116

Description

### What are you generating using Kiota, clients or plugins?

API Client/SDK

### In what context or format are you using Kiota?

Mac executable

### Client library/SDK language

None

### Describe the bug

Kiota fails to resolve local relative `$ref` references to external files on macOS (zsh) and also in the official Kiota Docker container.

Given an OpenAPI file (`petstore_minimal.json`) that references a second file in the same folder (`petstore_components_minimal.json`) via:

```
"$ref": "./petstore_components_minimal.json#/components/schemas/Pet"
```

Kiota tries to load the components file from the **parent directory** instead of the specification file’s directory. This breaks `kiota show` and `kiota generate` flows. On Windows (PowerShell) the same layout works as expected.

This behavior is not affected by using JSON vs YAML specs.

### Expected behavior

Kiota should resolve references correctly on any platform.

### How to reproduce

**Folder layout**
```
openapi/
petstore_minimal.json
petstore_components_minimal.json
```

From the `openapi` folder run `kiota show`:

```bash
kiota show -d petstore_minimal.json
```

which shows the following error:

```
crit: Kiota.Builder.KiotaBuilder[0]
error showing the description: Could not find file '/Users/username/petstore_components_minimal.json'.
```

It can be seen that Kiota expects the components file outside of the `openapi` folder.

### Open API description file

## petstore_minimal.json

```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"servers": [
{
"url": "http://petstore.swagger.io/v1"
}
],
"paths": {
"/pets/{petId}": {
"get": {
"summary": "Info for a specific pet",
"operationId": "showPetById",
"tags": [
"pets"
],
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"description": "The id of the pet to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "./petstore_components_minimal.json#/components/schemas/Pet"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "./petstore_components_minimal.json#/components/schemas/Error"
}
}
}
}
}
}
}
}
}

```

## petstore_components_minimal.json

```json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore components",
"license": {
"name": "MIT"
}
},
"paths": {},
"components": {
"schemas": {
"Pet": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"Error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
}
```

### Kiota Version

1.29.0+c21ebceb977bc33def3d8a9e5237b798a7b962b6

### Latest Kiota version known to work for scenario above?(Not required)

_No response_

### Known Workarounds

For docker runs, mapping the ref'd files differently works for simple definitions:

```dockerfile
docker run \
-v "${PWD}"/openapi/petstore_minimal.json:/app/openapi/petstore_minimal.json \
-v "${PWD}"/openapi/petstore_components_minimal.json:/app/petstore_components_minimal.json \
mcr.microsoft.com/openapi/kiota show --openapi /app/openapi/petstore_minimal.json \

```

### Configuration

Following configurations do not work:
- macOS Tahoe 26.2 with zsh 5.9
- Docker Image: mcr.microsoft.com/openapi/kiota:1.29.0

Following configuration does work:
- Windows 11 with PowerShell 7.5.4

### Debug output

```
dbug: Kiota.Builder.KiotaBuilder[0]
kiota version 1.29.0
info: Kiota.Builder.KiotaBuilder[0]
loaded description from local source
dbug: Kiota.Builder.KiotaBuilder[0]
step 1 - reading the stream - took 00:00:00.0036811
crit: Kiota.Builder.KiotaBuilder[0]
error showing the description: Could not find file '/Users/username/petstore_components_minimal.json'.
```

### Other information

_No response_

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the issue with petstore_minimal.json and petstore_components_minimal.json using `kiota show -d petstore_minimal.json`, then compare local $ref resolution on macOS and in the Docker image. Trace the file-loading path from the `kiota show` entry point; done means same-folder relative references resolve correctly for both `show` and `generate` across the reported environments.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.