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

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 or 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 and 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 and click New issue. Each package.json in the monorepo—including packages/core/package.json and 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 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. 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, 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:

## 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}