Essentials

Troubleshoot Meta VR CLI

Updated: Aug 27, 2026

Overview

This page covers problems that do not belong to one task. For install problems, see Install Meta VR CLI. For headset connection problems, see Work with devices and apps.

Your AI agent cannot reach Meta VR CLI

Your agent lists the same capability twice

Symptom: Your agent offers two of everything, picks an odd one of two similar actions, or is slow to start.

Solution: More than one Model Context Protocol (MCP) server is registered. Meta tools that bundle the CLI can each register their own, under their own name, so one does not replace another. Open your agent’s MCP configuration, keep the entry you want, remove the rest, and restart the agent. You can rename an entry there if two share a name.

The Meta Horizon Android Studio plugin registers no MCP server, so it never adds a duplicate.

Your agent shows nothing new after you install the server

Symptom:metavr mcp install <target> succeeded, but the agent offers no new capabilities.

Solution: Restart the agent. Agents read their MCP configuration at startup, so a change made while one is running takes effect at the next launch.

The server does not start

Symptom: Your agent reports that the Meta VR CLI server failed to start, or it never responds.

Solution: Run the server yourself and watch for an error:

metavr mcp server

That is the same process your agent launches. It speaks over stdio, which is the only transport it supports. Press Ctrl+C to stop it.

Your agent calls the server hzdb

Symptom: Your agent displays the server as hzdb, even though you registered it as metavr.

Solution: Nothing is wrong. The name you register is metavr, but the server still reports its own internal name as hzdb, from before the CLI was renamed. Both refer to the same server.

A command is missing

A command you read about is not in the help output

Symptom: A command you have seen documented does not appear in metavr --help, and running it gives you an unrecognized-command error instead of a permission error.

Solution: Check what your build offers:

metavr --help

Some commands ship inside the binary but stay switched off for an account until Meta enables them. While one is off, it is removed from the help output completely, which makes it look like it was never there. A command absent from your help output is either switched off for your account or absent from public builds.

metavr doctor says everything is fine

Symptom:metavr doctor reports no problems, but you still cannot reach a headset, sign in, or connect your agent.

Solution:metavr doctor reports which developer software it found on your machine. It does not test headset connections, sign-in, or your agent setup, so a clean report tells you nothing about those. Use the relevant section of this page instead.

Signing in

Installing and using Meta VR CLI works without an account, and metavr init offers to sign you in. Signing in is worth doing: it unlocks Meta Horizon Store commands and other account-backed features, and more will depend on it over time.

Symptom: A Meta Horizon Store command fails and asks you to run metavr auth login.

Solution: Sign in. Your browser opens to complete it:

metavr auth login

A script cannot tell that you are signed out

Symptom: A script checks the exit code of metavr auth status and always concludes you are signed in.

Solution:metavr auth status always exits 0. Read the status it prints instead of branching on the exit code.

metavr auth status

metavr whoami prints the signed-in identity.

A script needs a token and there is no flag for one

Symptom: You want to pass a token to a script or a continuous integration job, but --token does not exist.

Solution: Set an environment variable. The legacy name HZDB_TOKEN also works.

export METAVR_TOKEN=<your-token>

You need to sign out

Symptom: You want to clear stored credentials, or switch accounts.

Solution:

metavr auth logout

Add --local-only to clear credentials on this machine while leaving the Meta-side session alone. That is the only flag it takes. Tokens live in your operating system’s credential store under the service name Meta VR CLI.

Updating

metavr update succeeds but the version does not change

Symptom:metavr update finishes without an error, and metavr --version reports the same version as before.

Solution: What the command does depends on how you installed the CLI. A binary from the native installer updates itself. A binary from a package manager does not: the command prints a note that self-update is off, tells you to use your package manager, and then exits successfully. That success means the command ran, not that anything changed.

Use --dry-run to see what an update would do, --version <V> to pin a version, or --force to reinstall the current one.

Install Meta VR CLI: install the CLI and connect it to your AI agent.

Meta VR CLI overview: how the command line and the MCP server relate.

Work with devices and apps: headset setup and device problems.