# How to Report Bugs in Cordis: A Complete Guide to GitHub Issues

> Effectively report bugs in Cordis using GitHub Issues. Follow our guide for creating detailed bug reports with reproduction steps and environment info for quick resolution.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Report bugs in Cordis by opening a new issue on the GitHub repository, selecting the "Bug report" template, and providing detailed environment information, reproduction steps, and error logs from [`packages/core/src/fiber.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/fiber.ts) or [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts).**

Cordis is a modular plugin framework for Node.js, and when you encounter validation errors or runtime failures, submitting a detailed bug report helps the maintainers fix issues quickly. By following the structured approach outlined in the Cordis repository's issue templates and referencing specific source files like [`fiber.ts`](https://github.com/cordiverse/cordis/blob/main/fiber.ts) and [`loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/loader/src/index.ts), you can significantly reduce the time needed to diagnose and resolve problems.

## Step-by-Step Guide to Reporting Cordis Bugs

### 1. Open a New Issue on GitHub

Navigate to the [Cordis issues page](https://github.com/cordiverse/cordis/issues) and click **New issue**. Each [`package.json`](https://github.com/cordiverse/cordis/blob/main/package.json) in the monorepo—including [`packages/core/package.json`](https://github.com/cordiverse/cordis/blob/main/packages/core/package.json) and [`packages/utils/package.json`](https://github.com/cordiverse/cordis/blob/main/packages/utils/package.json)—contains a `bugs` field that points to this centralized issue tracker, confirming this is the correct location for all bug reports.

### 2. Select the Bug Report Template

Choose the **"Bug report"** template if available. If not, start your issue title with a clear prefix like `Bug: ...` to help maintainers triage quickly. Using the template ensures you don't miss critical sections that the Cordis team needs to reproduce your issue.

### 3. Provide Essential Diagnostic Information

Fill out each section of the template with the following details:

- **Environment** – OS, Node.js version, and Cordis version (run `npm list cordis` or `pnpm ls cordis` to check)
- **Steps to reproduce** – A minimal code snippet or configuration that triggers the bug
- **Expected behaviour** – What you believe should happen
- **Actual behaviour** – Error messages, stack traces, and logs (e.g., `ctx.logger.error(...)` output)
- **Configuration files** – Relevant portions of [`cordis.config.ts`](https://github.com/cordiverse/cordis/blob/main/cordis.config.ts) or plugin settings

## Key Information to Include in Your Bug Report

When reporting bugs in Cordis, specific technical details dramatically speed up the debugging process:

1. **Validation Error Context** – If you see configuration validation errors, quote the exact message from the `ValidationError` class defined in [`packages/core/src/fiber.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/fiber.ts). This file handles core validation of plugin configuration and generates the error messages that appear when config schemas fail.

2. **Loader Stack Traces** – For plugin initialization failures, include the full stack trace from [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts), which serves as the entry point for loading plugins and handling load-time errors.

3. **Logger Output** – Include the full output of the Cordis logger at `error` or `debug` levels, especially when reporting runtime failures or broken plugins.

4. **Package Versions** – List all relevant packages (e.g., `@cordis/core@4.0.0-rc.10`, `@cordis/loader@4.0.0-rc.10`) since Cordis is a monorepo with interconnected packages.

## Example Bug Report Template

Use this markdown structure to ensure your report contains all necessary technical details:

```markdown

## Description

A short description of the problem.

## Environment

- OS: Windows 11
- Node.js: 20.x
- Cordis version: 4.0.0-rc.10
- Packages: `@cordis/core@4.0.0-rc.10`, `@cordis/loader@4.0.0-rc.10`

## Steps to reproduce

1. Create a `Cordis` instance with the following config:
   ```ts
   import { Cordis } from '@cordis/core'
   const app = new Cordis({ /* ... */ })
   ```

2. Load the plugin `my-plugin` that triggers the error.
3. Call `app.start()`.

## Expected behaviour

The plugin should start without throwing.

## Actual behaviour

```

Error: invalid config:
  - unknown field `foo` (at plugin.options.foo)

```

## Additional context

- Stack trace (if any):

```

at Plugin.validate (node_modules/@cordis/core/src/fiber.ts:41:15)

```

- Relevant config file:

```ts
export default {
  plugins: [{ name: 'my-plugin', options: { foo: 'bar' } }],
}

```

```

## Summary

- **Open issues** on the [official Cordis GitHub repository](https://github.com/cordiverse/cordis/issues), as specified in the `bugs` field of [`packages/core/package.json`](https://github.com/cordiverse/cordis/blob/main/packages/core/package.json) and [`packages/utils/package.json`](https://github.com/cordiverse/cordis/blob/main/packages/utils/package.json).
- **Include environment details** (OS, Node.js, Cordis version) and **reproduction steps** using minimal code examples.
- **Reference specific source files** when quoting errors: use [`packages/core/src/fiber.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/fiber.ts) for validation errors and [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts) for plugin loading failures.
- **Attach complete logs** from `ctx.logger.error()` or debug output to help maintainers trace execution flow.

## Frequently Asked Questions

### Where do I report bugs in Cordis?

Report all bugs on the [GitHub issues page](https://github.com/cordiverse/cordis/issues) for the `cordiverse/cordis` repository. The `bugs` field in [`packages/core/package.json`](https://github.com/cordiverse/cordis/blob/main/packages/core/package.json) and [`packages/utils/package.json`](https://github.com/cordiverse/cordis/blob/main/packages/utils/package.json) both point to this centralized tracker, ensuring your report reaches the correct maintainers regardless of which specific package contains the bug.

### What should I include in a Cordis bug report?

Include your operating system, Node.js version, Cordis version (from `npm list cordis`), minimal reproduction code, expected behavior, actual error messages, and relevant configuration files like [`cordis.config.ts`](https://github.com/cordiverse/cordis/blob/main/cordis.config.ts). If the error originates from config validation, quote the specific `ValidationError` message from [`packages/core/src/fiber.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/fiber.ts).

### How do I find the Cordis version I'm using?

Run `npm list cordis` or `pnpm ls cordis` in your project root to display the installed version. Since Cordis uses a monorepo structure with packages like `@cordis/core` and `@cordis/loader`, also include the versions of these sub-packages in your bug report to help maintainers identify version-specific issues.

### What if I don't know which file caused the error?

Include the **complete stack trace** from your error output. Cordis errors typically originate from two key locations: [`packages/core/src/fiber.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/fiber.ts) (for configuration validation errors) or [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts) (for plugin loading failures). The stack trace line numbers will help maintainers identify whether the issue is in the core validation logic or the plugin loader initialization.