metasploit "failed to load module" error on authorized test

TL;DR

A module that fails to load is broken before it ever runs: a syntax error in a custom or edited module, a missing gem or library, or a stale module cache after an update. Read the load error with verbosity up, test the module file directly if it is custom, rebuild the module cache, and only then suspect the framework install.

metasploit "failed to load module" error on authorized test

Use this when

• Selecting a module reports failed to load module, or the module is missing from search results after an update.
• The module is a custom or locally edited one for the engagement.

Not for this skill when

• The module loads and the run fails against the lab target. That is target behaviour, diagnosed at run time.
• The module was removed or renamed upstream. Loading the successor module is the fix, not repair.

Steps

1. Capture the full load error: start msfconsole with verbose module loading or reload the one module and save the complete error and any backtrace. Verify: Verify: the error names a file and a reason, such as a syntax error or a missing require.
2. If the module is custom or edited, open that file at the named line and fix the syntax or the broken edit, comparing against the upstream version of the module if one exists. Verify: Verify: the file parses cleanly with the language's syntax check.
3. If the error names a missing library or gem, install the dependency the framework expects through its own bundle or package route rather than a random system package. Verify: Verify: the dependency loads in the framework's environment.
4. Rebuild the module cache from within msfconsole or by removing the stale cache so the framework rescans all module paths. Verify: Verify: search now finds the module with its current description.
5. Load the module, run its check or options display against no target, and confirm info renders completely before using it on the authorized lab. Verify: Verify: the module loads, shows options, and is ready for a scoped run.

Variant phrasings

metasploit custom module syntax error failed to load

The custom-module phrasing.

msf module missing after update rebuild cache

The cache phrasing.

metasploit module load error missing gem require

The dependency phrasing.

Compatibility: Compatibility: Metasploit Framework 6.x module paths for packaged, user, and custom modules; user modules live under the operator's home configuration.

Why it happens

Modules are code loaded at runtime from several paths, and the loader reports one generic failure for many distinct causes: bad edits, broken dependencies, and caches that point at files an update moved. The backtrace separates them instantly, while guessing leads people to reinstall the whole framework for what was a one-line typo in a custom module.

Edge cases / pitfalls

• Keep custom engagement modules in version control; the diff against the last working version is usually the bug.
• A module copied from a forum post may target an older framework API; check its date and API calls before debugging your install.
• Do not edit packaged modules in place: copy to the user module path and edit there, so updates do not erase or conflict with your change.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstXybiMui1r0rQBXQv0Hx4A