Preserve the package-owned dependency boundary
Record the actual launcher, environment, package source and first relevant error. Review a simulated package transaction before restoring packaged files. Do not edit a distribution lockfile or install arbitrary global gems merely to silence one message. Loading the console, reading a module and using the database are separate checks, and none requires launching an exploit. Source and scope.
A Ruby or Bundler error after a Kali update does not identify one universal fix. First determine which Metasploit installation and runtime are actually used, whether the package transaction completed and what the first meaningful error says. Then choose environment correction, package repair or a documented restoration of a known-good environment.
This guide focuses on Kali’s packaged Metasploit and explains where a separately maintained source checkout differs. It does not provide a tested version matrix, guaranteed rollback or measured repair time. References were checked on October 16, 2026; no package, Ruby installation or Metasploit database was changed for this article.
Identify the installation you intend to maintain
Distinguish an APT package from a Rapid7 installer or source checkout using a project-specific Ruby environment. Do not apply commands to one installation while launching another. Kali’s Metasploit package page lists its supported package and tools; installed paths and dependencies should be checked on your machine rather than copied from a dated version claim.
Back up needed configuration, workspaces and evidence before repair. Record the normal user context and working directory. An error that appears only as one user is useful evidence about that context, not a reason to run the framework as root indefinitely.
Capture the exact failure without overclassifying it
Start with msfconsole -v and preserve the first meaningful error plus the context needed to interpret the stack trace. Redact usernames, tokens, connection strings and private paths before sharing. A fixed first-25-lines cutoff may omit the important cause.
A declared Ruby-version conflict, a missing gem, a Bundler warning and a native-extension LoadError are different leads. “Cannot load such file” does not by itself prove an OpenSSL ABI mismatch. Check the named file and complete error instead of assuming every post-update failure has the same cause.
Compare the shell selection with the launcher
The commands below inspect command selection, versions and package state. Run them in the context that fails. Shell-selected ruby and bundle are clues; a launcher can select an interpreter or change its environment, so these outputs do not conclusively identify everything used inside msfconsole.
Inspect the actual launcher and package ownership when paths disagree. Check relevant GEM_HOME, GEM_PATH, RUBYOPT, RUBYLIB and BUNDLE_* overrides without publishing their values indiscriminately. A new terminal can load the same startup files and is not automatically a clean environment.
type -a msfconsole ruby bundle bundler
ruby -v
ruby -rrbconfig -e 'puts RbConfig.ruby'
bundle -v
apt-cache policy metasploit-framework ruby bundler
dpkg --audit
apt-mark showholdRead the lockfile without rewriting the package
Bundler’s dependency-management guide explains Gemfile.lock as the resolved dependency record. Examine its platforms and any Ruby or BUNDLED WITH metadata in the context of the installed application. The recorded Bundler version is not a universal rule that every other version must fail.
For a Kali-managed application, avoid editing its lockfile or running bundle update to force a new resolution before understanding the package state. A source checkout has a separate dependency-maintenance workflow; follow its documented Ruby and Bundler requirements in an isolated environment.
Choose an environment or package repair from the evidence
If the verified packaged launcher works with intended distro paths and relevant user overrides removed, but fails in the usual shell, compare those differences. Change one setting reversibly and retest. That result narrows the cause; it does not prove every installed package or database is healthy.
If package state is incomplete or inconsistent, first resolve repository and transaction errors using Kali’s update guidance. Review the proposed transaction before applying it. Do not add another distribution’s repositories or disable signature checks to satisfy one dependency.
The following APT simulation previews a reinstall plan; it does not perform the repair or guarantee success. It uses the current local package metadata, which may be stale. Review proposed removals, dependency changes, available versions and errors before choosing an actual transaction.
apt-get -s install --reinstall metasploit-frameworkSeparate restoration, holds and pinning
A rollback requires an available, verified compatible package set or a suitable known-good backup. Choosing an older version of only Ruby, Bundler or Metasploit can create another incompatibility. Compare the installed and proposed dependency sets and test in a recoverable environment before relying on the change.
A hold does not downgrade, repair or freeze all dependencies of a named metapackage. APT preferences influence version selection and are a different mechanism, explained in apt_preferences. Neither is a complete reproducibility strategy. Avoid a blanket hold command presented as a default fix.
Any temporary restriction needs its package scope, reason, owner, review date and removal/retest plan. It can delay security updates. Needing stability for two weeks alone does not justify pinning: a tested environment snapshot with separate data backups may better fit the requirement.
Avoid destructive dependency shortcuts
Do not delete gem directories at random, replace shared-library symlinks or globally install another Bundler merely because the error names Bundler. Package repair does not necessarily remove conflicting user-installed gems or undo local configuration, so a reinstall may leave the original cause in place.
Keep system-managed dependencies separate from intentional Ruby development environments. Preserve logs and configuration before changing them. Compare permissions and paths when user/root behavior differs, rather than recursively changing ownership across a Ruby installation.
Investigate native libraries and architecture separately
For a native-extension error, identify the specific extension, runtime, architecture and missing dependency or symbol. A warning mentioning OpenSSL is a clue, not sufficient evidence for copying a library from another system. Avoid suppressing the loader error instead of resolving the supported dependency set.
Record the architecture and repository suite when reporting package availability problems. ARM and x86-64 installations need their own compatible artifacts. Repository authentication or metadata errors should be resolved before interpreting a proposed reinstall as a coherent repair.
Verify startup, modules and database as separate checks
Repeat msfconsole -v in the intended user context after a reviewed correction. Then open the console and inspect help or module information without launching an action against a target. Successful startup does not validate every module.
If you use database-backed features, inspect their connection status separately and preserve existing workspaces. Do not run a database reset or reinitialization as a generic response to a Ruby error. A disconnected database and a framework startup failure are different conditions.
Record the exact check and result; this is a smoke test, not a guarantee against future rolling-update regressions. No exploit, listener or target interaction is required merely to establish that the console and module information load.
Common questions
Should I install the newest Bundler globally? Not as an undiagnosed fix for a distro-managed application. Confirm the launcher, dependency requirements and environment first.
Does holding the broken packages fix the error? No. It preserves a selection state; restore a compatible working state first and review whether a temporary restriction is warranted.
Keep a useful recovery note
Save the failure message, installation source, launcher, user context, package versions, relevant environment differences, package transaction and verification results. Record temporary holds or preferences explicitly. Keep secrets out of the shareable note.
The Zsh setup guide explains startup context and recovery boundaries that can help distinguish shell drift from application packaging. A recovery note should describe the observed comparison, not just a command that appeared to work once.
Match the fix to the confirmed layer
Capture the failure, verify the intended installation and compare runtime and package state. Make a reversible, evidence-based correction and retest the capabilities you need. Treat an unresolved result as unresolved instead of promising that pinning or reinstallation will repair every Ruby/Bundler error.