Troubleshooting

Quick diagnostics

Run these first when something isn't working:

# Confirm the CLI version
megaport-cli version

# Confirm authenticated identity (user, company, environment, profile)
megaport-cli whoami

# Test credentials (succeeds silently if auth works)
megaport-cli locations list --output json > /dev/null

Authentication failures

Symptoms: 401 Unauthorized, authentication failed, invalid credentials

Causes and fixes:

# Check what credentials and environment are active
megaport-cli config view

# Override with environment variables for a single command
MEGAPORT_ACCESS_KEY=key MEGAPORT_SECRET_KEY=secret megaport-cli ports list

# Or use a named profile
megaport-cli ports list --profile staging

Resource not found

Symptoms: resource not found, 404, no port/VXC/MCR found with UID

Causes and fixes:

# List with inactive resources included
megaport-cli ports list --include-inactive --output json

# Verify UID exists
megaport-cli ports get <uid>

Validation errors

Symptoms: validation error, invalid value, field is required

# Validate without provisioning
megaport-cli ports validate --json-file ./port.json
megaport-cli vxc validate --json-file ./vxc.json
megaport-cli mcr validate --json-file ./mcr.json

VXC provisioning failures

Symptoms: VXC stuck in CONFIGURED, partner config error, VLAN conflict

# Check whether a specific VLAN is available on a port
megaport-cli ports check-vlan <portUID> <vlan>

# Find partner ports at a location
megaport-cli partners list --company-name "Amazon Web Services" --location-id 3 --output json

Browser terminal (WASM) issues

Symptoms: Terminal doesn't load, commands fail, auth errors in browser

Loading failures:

The WASM binary is ~21 MB. It loads on page render, so wait for the download to complete before entering credentials. If loading stalls, hard-refresh (Cmd+Shift+R / Ctrl+Shift+R).

Browser compatibility: Chrome, Firefox, and Edge have full WebAssembly + SharedArrayBuffer support. Safari 16.4+ is supported. Older Safari versions may fail silently.

Commands not available in browser:

--interactive / -i does work in the browser: prompts are answered inline in the terminal, and password prompts are masked. For piping and config, use the --json or --json-file input modes and --output json instead.

Auth errors after connecting:

• Credentials are passed to WASM after the terminal initializes. If you see auth errors immediately, wait 1–2 seconds and retry the command.
• Refresh the page and re-enter credentials if auth state becomes stale.

Memory: If the browser tab crashes on large result sets, try adding --output json and paginating with filters (--metro, --location-id, etc.).

Output and formatting issues

Large result sets: For accounts with many resources, --output table may truncate. Switch to --output json and pipe to jq:

megaport-cli ports list --output json | jq 'length'
megaport-cli ports list --output json | jq '[.[] | {name, uid, status}]'

CSV encoding: CSV output uses standard comma-separation with quoted fields. If a field contains commas, the value will be quoted automatically.

XML output: The --output xml format is available but less commonly used. Some tools may require the output to be wrapped in a root element — pipe through your preferred XML processor.

Behaviour changes in v0.10 and later

Defaults and supported flags shifted across v0.10, v0.11, v0.12, and v0.13. If a script that worked under an older release now misbehaves, check here first.

JSON output keeps stderr separate from stdout

In --output json mode, only the JSON payload goes to stdout. Warnings, progress messages, and informational notices are written to stderr. This means piping directly to jq works without filtering:

megaport-cli ports list --output json | jq '.[] | .name'

If you previously stripped warning lines with grep, you can remove that step. To capture warnings, redirect stderr separately:

megaport-cli ports list --output json 2> warnings.log | jq '.'

Port, MCR, and MVE deletion is immediate

Deletion no longer defers to the end of the billing cycle for these resource types. There is no --now or --later flag — delete removes the resource right away. Restore is only possible while the resource is in DECOMMISSIONING; once it reaches DECOMMISSIONED, restoration is no longer possible. Lock production resources with ports lock / mcr lock / mve lock if you want a safety check.

VXC and IX deletion stayed flexible

vxc delete and ix delete are immediate by default, but accept --later to schedule cancellation at the end of the billing cycle. Transit VXCs do not support --later.

NAT Gateway deletion has no restore window

nat-gateway delete is permanent — once removed there is no way to bring the gateway back. Confirm before running, especially in scripted flows.

--base-url / --token-url overrides

Both flags landed in v0.11 — --base-url targets a non-default API endpoint without switching --env, and --token-url overrides the OAuth token endpoint when it sits on a different host. Useful for staging or dev hosts. The CLI emits a warning if either URL is not HTTPS.

mve update --contract-term is now --term (v0.12)

The flag was renamed for consistency with mve buy. Scripts passing --contract-term to mve update will fail with an unknown-flag error — switch them to --term. The JSON field is unchanged (contractTermMonths in --json / --json-file).

mve update can rename vNICs (v0.12)

mve update accepts --vnics to change vNIC descriptions in place — one entry per existing vNIC, in order. Only description is mutable; the vNIC count and VLANs are fixed once the MVE is provisioned. Passing a different number of vNICs, or any key other than description, is rejected.

Browser terminal: repeated list commands returning no results (v0.12)

Earlier WASM builds leaked --tag filter state between commands, so running ports list (or vxc / mcr / mve list) twice in one browser session could return "No resources found" on the second run even with no filter set. v0.12 resets array flags correctly between invocations. If you hit this on the in-browser terminal, do a hard refresh to pick up the current build.

mcr update can change the BGP ASN and term (v0.13)

mcr update now accepts --mcr-asn to change the MCR's BGP ASN, and --term to move it to a different contract term (1, 12, 24, or 36 months). Changing the ASN re-runs BGP setup on the MCR, so existing peering sessions may briefly flap. The same guidance as mcr buy applies: 64512-65534 for a private ASN, or a public ASN.

Client-side validation for IX and MCR ASN (v0.13)

ix buy, ix update, mcr buy, and mcr update now validate input locally before calling the API, so you get a clear error up front instead of a generic API rejection. IX checks the ASN (1-4294967295), MAC address (EUI-48, for example 00:11:22:33:44:55), VLAN (0 to auto-assign, -1 for untagged, or 2-4094), and rate limit (must be a positive number). MCR checks the ASN range on both buy and update.

servicekeys update no longer resets fields, and --description is gone (v0.13)

A few changes here:

• Omitting --active or --single-use no longer flips them to false. The command reads the current key and changes only the flags you pass.
• --description was removed because the update API does not support changing it. Set the description at create time with servicekeys create --description. A script passing --description to servicekeys update now fails with an unknown-flag error.
• Passing both --product-uid and --product-id is rejected instead of being sent to the API.
• The command exits non-zero if the API reports the change was not applied (it used to warn and exit 0).

Empty lists return a valid document, and --output is case-insensitive (v0.13)

A list with no results now emits a valid empty document instead of nothing: [] for JSON, a header-only row for CSV, and an empty root element for XML. table output prints just the column headers with no data rows. --output now accepts any casing, so --output JSON and --output Json behave the same as --output json.

Clearer errors and exit codes (v0.13)

• Invalid whole-number arguments produce a readable message (for example 'abc' is not a valid whole number) instead of a raw parser error.
• A malformed --json / --json-file payload is treated as a usage error and exits 2 (it previously looked like an API error, exit 4).
• A delete, restore, lock, unlock, or update that the API reports as not applied now exits non-zero instead of 0.
• Missing required arguments exit 2 (usage) rather than 1.

Buy and order commands no longer retry on ambiguous failures (v0.13)

Provisioning commands (buy, apply, nat-gateway create) retry only on rate limits (429) and connections refused before the request was sent. Ambiguous gateway errors (502, 504), where the order may already have been accepted upstream, are no longer retried automatically, to avoid double-ordering. If you hit one, check whether the resource was created with ... list or ... get before re-running.

Browser terminal: new commands and masked passwords (v0.13)

The in-browser terminal now runs four more read-only modules: nat-gateway, status, topology, and product. The terminal also masks password prompts the same way the installed CLI does, so any sensitive value is hidden as you type it. As always, do a hard refresh to pick up the current build.

locations list-market-codes drops blank entries (v0.13)

Empty or whitespace-only market codes are filtered out, so the list no longer shows blank rows or an inflated count.

Getting help

Built-in help

Every command has a --help flag:

megaport-cli --help
megaport-cli ports --help
megaport-cli ports buy --help

Verbose and HTTP logging

Two global flags help diagnose API-level problems:

# Show extra debug information
megaport-cli ports list --verbose

# Log raw HTTP requests and responses to stderr (may include auth tokens)
megaport-cli ports list --log-http 2> http.log

--log-http writes the full request/response trace to stderr — useful when filing a bug, but redact the Authorization header before sharing the log.

Version check

megaport-cli version

Include the version when reporting bugs — the auto-generated docs in docs/ correspond to the installed version.

Support

• API status: status.megaport.com
• Portal: portal.megaport.com — manage API keys, view resources, raise support tickets
• CLI issues: github.com/megaport/megaport-cli — bug reports and feature requests