How to Report Bugs in OpenEnv: The Complete Guide to GitHub Issues

To report bugs in OpenEnv, open a GitHub Issue with a "Bug:" prefix, include environment details and a reproducible code snippet, and follow the standardized template defined in CONTRIBUTING.md to help maintainers triage and fix issues efficiently.

OpenEnv is an early-stage, agent-first framework where bugs and missing features are expected during active development. The Hugging Face team maintains a clear, standardized process for reporting problems to ensure rapid triage and resolution. Following the official workflow documented in the repository's contributing guidelines ensures your bug report contains the actionable information developers need.

Review the Official Guidelines

Before creating an issue, consult the CONTRIBUTING.md file at the repository root. Lines 23-27 of this document specify the required information structure and mandatory fields for bug reports. The guide also references the Meta bounty program for security-critical vulnerabilities that require private disclosure rather than public GitHub issues.

Step-by-Step Bug Reporting Process

Follow these eight steps to submit a complete, actionable bug report:

1. Navigate to the GitHub Issues tracker – All public bugs are tracked at https://github.com/huggingface/OpenEnv/issues.

2. Prefix your title – Start the issue title with "Bug:" or "Bug – " followed by the component name, such as Bug: EchoEnv step() returns wrong reward.

3. Select the bug label – Apply the bug label from the dropdown to ensure proper categorization.

4. Fill the issue body using the template – The README.md (lines 85-92) acknowledges that bugs are expected in this early-development phase and encourages detailed reporting. Use this exact structure:

### Description

A short, one-sentence summary of the problem.

### Environment

- OpenEnv version: `pip show openenv` (or `git rev-parse HEAD`)
- Python version: `python --version`
- Operating system: e.g. Ubuntu 22.04, macOS 14.5
- Environment client (e.g. `echo_env`) version

### Steps to Reproduce

1. Provide the minimal code snippet that triggers the bug.
2. Show the exact command you run (e.g., `python script.py` or `uv run ...`).
3. Include any relevant configuration files (`openenv.yaml`, `pyproject.toml`).

### Expected Behavior

What you think should happen.

### Actual Behavior

What actually happens (error messages, stack traces, incorrect rewards, etc.).

### Additional Context

- Logs (remove any secret values; only keep the log level and messages).
- Screenshots or terminal output if helpful.

5. Redact sensitive information – Remove API keys, tokens, and credentials before posting. For security-critical bugs, follow the private reporting process mentioned in CONTRIBUTING.md rather than opening a public issue.

6. Attach a minimal reproducible test (optional) – If the bug affects a specific environment like coding_env, include a short pytest case under tests/ and reference it in the issue to accelerate verification.

7. Respond to follow-up requests – Maintainers may request additional logs, configuration details, or reduced test cases. Prompt responses help close issues faster.

8. Verify the fix – Once resolved, test the fix against your original reproduction case before closing the issue.

Minimal Reproducible Example

Include a concise code snippet that demonstrates the failure. For example, this script reproduces a typical typo-induced bug in the Echo environment:

import asyncio
from echo_env import CallToolAction, EchoEnv

async def main():
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        await client.reset()
        # Intentional mistake: misspelling the tool name

        result = await client.step(
            CallToolAction(
                tool_name="ech_message",  # <-- typo triggers bug

                arguments={"message": "Hello"}
            )
        )
        print(result)

asyncio.run(main())

When executed, this raises a ToolError with a TOOL_NOT_FOUND enum value. Paste the full traceback into the issue body under Actual Behavior.

Key Files for Reference

Understanding these source files helps you write more precise bug reports:

• CONTRIBUTING.md – Defines the official bug-reporting workflow, required information fields, and security disclosure procedures.
• README.md – Contains the early-development disclaimer (lines 85-92) acknowledging expected bugs and encouraging user reports.
• src/openenv/core/README.md – Documents the core architecture; essential when reporting low-level client/server API bugs.
• envs/echo_env/README.md – Details Echo client usage; reference this when filing bugs against specific environment implementations.

Summary

• OpenEnv is early-stage software where bugs are expected; the maintainers actively encourage detailed reports through GitHub Issues.
• Always check CONTRIBUTING.md before filing to ensure you include mandatory environment details and follow the security disclosure policy.
• Use the "Bug:" prefix and standardized template to help maintainers reproduce issues quickly.
• Include minimal code examples and full tracebacks to demonstrate the failure mode.
• Never post secrets publicly; use private channels for security-critical vulnerabilities.

Frequently Asked Questions

Where do I report security vulnerabilities in OpenEnv?

For security-critical bugs involving API keys or authentication tokens, do not open a public GitHub Issue. Instead, follow the private reporting process outlined in CONTRIBUTING.md, which references the Meta bounty program for responsible disclosure. Redact all sensitive values when posting public bug reports.

What information is mandatory when reporting bugs in OpenEnv?

According to CONTRIBUTING.md lines 23-27, you must provide your OpenEnv version, Python version, operating system, and environment client version. You must also include steps to reproduce, expected behavior, and actual behavior with stack traces. The README.md (lines 85-92) reinforces that detailed reports help the team address issues faster during this early development phase.

How should I format the title of my bug report?

Prefix the title with "Bug:" or "Bug – " followed by the specific component name, such as Bug: EchoEnv step() returns wrong reward. This naming convention enables automatic triage and helps maintainers identify the affected subsystem immediately. Always apply the bug label from the GitHub Issues dropdown.

Can I submit a test case with my bug report?

Yes, attaching a minimal reproducible test accelerates the fix process. Create a short pytest case under the tests/ directory that demonstrates the failure, then reference the test file in your GitHub Issue. This is particularly valuable for environment-specific bugs in components like coding_env or echo_env.

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