underscore in folder name crashes “ignite scaffold module mymodule”

by

Summary

An underspecified project root directory (space_chain) caused the Ignite CLI scaffold command to create protobuf directory structures with an inconsistent naming scheme (spacechain vs. space_chain). This mismatch triggered a panic in the gogoproto plugin because the physical file paths (spacechain/customcheck/params.proto) did not match the logical package qualifiers expected by the Go imports (space_chain/customcheck). The build fails during the Protobuf code generation step.

Root Cause

The issue stems from a collision between filesystem conventions and Go module naming conventions.

  1. Directory Generation Logic: When running ignite scaffold module customcheck, Ignite generates a new module structure. It appears to sanitize or normalize the project root folder name for directory generation, stripping the underscore to create spacechain.
  2. Path Inconsistency: The tool created the physical directory proto/spacechain/... (without underscore).
  3. Import Path Mismatch: The existing Go code and go.mod are defined under the actual path space_chain. The generated params.proto file likely contains a package space_chain.customcheck; declaration (derived from the Go module path) but resides in the directory spacechain/....
  4. Plugin Panic: The gogoproto generator enforces a strict rule: physical path must equal logical package. The generator expected the file to be located at space_chain/customcheck/ (matching the package declaration) but found it at spacechain/customcheck/, resulting in the panic: “file name spacechain/customcheck/params.proto does not start with expected space_chain/customcheck”.

Why This Happens in Real Systems

  • Sanitization vs. Identity: Many CLI tools sanitize names to ensure compatibility with C-identifier standards, filenames, or internal registries, often stripping special characters like underscores. However, Go treats underscores as valid characters in module paths.
  • Legacy Tooling Assumptions: Older Protobuf ecosystems (and tools relying on them like gogoproto) often assume a 1:1 mapping between directory structure and package hierarchy.
  • Scope Ambiguity: Ignite derives the package name from the project folder name on disk. If the folder name contains characters that the scaffolding engine handles inconsistently (e.g., ignores during directory creation but respects during package declaration), a divergence occurs immediately upon file generation.

Real-World Impact

  • Blocker: The build pipeline halts entirely; no code is generated for the new module.
  • Project Corruption: If manual fixes are attempted (renaming folders), existing imports in the codebase may break, requiring a global search-and-replace across the entire application.
  • Developer Velocity: Requires understanding the deep internals of the Protobuf generation chain to debug, which is often outside the scope of standard blockchain module development.

Example or Code

The error stack trace provided highlights the specific assertion failure in the gogoproto library:

panic: file name spacechain/customcheck/params.proto does not start with expected space_chain/customcheck/

This indicates that while the file was written to spacechain/customcheck/params.proto, the generator expected the path segment space_chain.

How Senior Engineers Fix It

  1. Preserve Path Consistency (Recommended):

    • Rename the project root folder from space_chain to spacechain.
    • Update go.mod to module github.com/imbamf/spacechain.
    • Crucially: Run a global search and replace in the codebase (e.g., sed -i 's/space_chain/spacechain/g' $(find . -name "*.go")) to update all import paths.
    • For Production Networks: If you have an existing mainnet or testnet, this requires a hard fork and a state migration (importing the old state into the new binary). Simply renaming a running node will cause consensus failures because the application hash will change.

  2. Patch the Protobuf Build (Workaround):

    • If you cannot change the module name (e.g., due to existing on-chain deployments), you must manually align the directories.
    • Rename the generated directory: mv proto/spacechain proto/space_chain.
    • Verify that proto/buf.yaml and proto/buf.gen.*.yaml files point to the correct paths. You may need to edit the go_package options in your .proto files to match the actual Go import path, but this often creates a loop with the generator.

  3. Tooling Versioning:

    • Check the compatibility matrix between the Ignite version and the Cosmos SDK version. Sometimes downgrading or upgrading Ignite resolves path sanitization issues, though in this specific case, the issue is fundamental to the project structure.

Why Juniors Miss It

  • Focus on Logic, Not Structure: Juniors often focus on writing Go logic and smart contract code but treat the project folder name and go.mod module path as static boilerplate.
  • Hidden Dependencies: The link between the physical folder name (e.g., space_chain) and the internal Proto package declaration (package space_chain.customcheck;) is not always obvious.
  • “It looks similar”: spacechain vs space_chain is visually easy to gloss over in terminal output, especially when the error message presents both.
  • Assumption of Tools: Assuming that a tool like Ignite will automatically handle all pathing correctly, without realizing that it relies on strict string matching between the filesystem and the Go module system.