HHE404: Task "ignition" not found on macOS 12.7 with Hardhat v3 and @nomicfoundation/hardhat-ignition-viem Context

[dgnhub]

Title: HHE404: Task "ignition" not found on macOS 12.7 with Hardhat v3 and @nomicfoundation/hardhat-ignition-viem
Context
Hardhat Version: 3.0.3 (and others attempted)

Plugin Versions:

@nomicfoundation/hardhat-toolbox-viem: 5.0.0

@nomicfoundation/hardhat-ignition-viem: 3.0.2

Operating System: macOS Monterey 12.7

Node.js Version: 22.19.0 (via nvm)

npm Version: 10.9.3

Description

When attempting to use the ignition task in a newly initialized project, Hardhat consistently fails with Error HHE404: Task "ignition" not found.

This issue occurs in a monorepo setup combining a Next.js v14 frontend with a Hardhat v3 backend. The error persists despite following all standard setup procedures and extensive troubleshooting, including multiple clean reinstalls of all dependencies.

The evidence suggests that while the @nomicfoundation/hardhat-ignition-viem plugin is correctly installed in node_modules and imported in hardhat.config.ts, it is failing to properly register the ignition task with the Hardhat runtime on this specific OS and dependency combination.

Steps to Reproduce
Initialize the project with the following package.json:

{
  "name": "hardhat-v3-ignition-testcase",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@openzeppelin/contracts": "^5.0.2",
    "next": "^14.2.4",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "viem": "^2.16.2",
    "wagmi": "^2.10.8"
  },
  "devDependencies": {
    "@nomicfoundation/hardhat-ignition-viem": "^3.0.2",
    "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0",
    "dotenv": "^16.4.5",
    "hardhat": "^3.0.3",
    "typescript": "^5.4.5"
  },
  "type": "module"
}

Perform a clean install:

rm -rf node_modules package-lock.json
npm install

Create a minimal hardhat.config.ts:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox-viem";
import "@nomicfoundation/hardhat-ignition-viem";
import "dotenv/config";

const config: HardhatUserConfig = {
  solidity: "0.8.20",
};

export default config;

Create a minimal Solidity contract contracts/Test.sol:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.20;
contract Test {}

Create a minimal Ignition module ignition/modules/Deploy.ts:

import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";

const TestModule = buildModule("TestModule", (m) => {
  const test = m.contract("Test");
  return { test };
});

export default TestModule;

Attempt to run the ignition task:

npx hardhat ignition deploy ignition/modules/Deploy.ts --network localhost

Expected Behavior

The ignition task should be recognized, and the deployment process should begin.

Actual Behavior

The command fails immediately with the HHE404 error.

Stack Trace

Error HHE404: Task "ignition" not found

HardhatError: HHE404: Task "ignition" not found
    at main (/Users/XXX/dev/app/node_modules/hardhat/src/internal/cli/main.ts:168:13)
    at async file:///Users/XXX/dev/app/node_modules/hardhat/dist/src/cli.js:21:1

Troubleshooting Performed
Verified that all necessary packages (hardhat, @nomicfoundation/hardhat-ignition-viem) are present in node_modules.

Verified that the plugin is correctly imported at the top of hardhat.config.ts.

Performed multiple "nuke and pave" reinstallations (rm -rf node_modules package-lock.json && npm install).

Restarted the machine to clear any OS-level resource issues.

Confirmed there are no other global or conflicting Hardhat installations.

The issue appears to be a silent failure during the plugin registration phase within the Hardhat core, possibly due to an environmental incompatibility with macOS 12.7. The short stack trace indicates the error occurs before Hardhat even begins processing the task-specific logic.

[kanej]

Hey, thanks for the details. There have been some changes in Hardhat 3 in the setup of config. You can see a default setup by running hardhat --init and creating a new sample.

You need to pass the toolbox plugin explicitly as a plugin (in Hardhat 2, the plugin was registered implicitly on import):

import hardhatToolboxViemPlugin from "@nomicfoundation/hardhat-toolbox-viem";

const config: HardhatUserConfig = {
  solidity: "0.8.28",
  plugins: [hardhatToolboxViemPlugin],
};

export default config;