Troubleshooting
Common errors, debugging tips, and diagnostics for the Megaport CLI
Quick diagnostics
Run these first when something isn't working:
# Confirm the CLI version
megaport-cli version
# 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:
| Cause | Fix |
|---|---|
| Wrong access or secret key | Double-check in portal.megaport.com → My Account → API & Credentials |
| Using staging credentials against production API (or vice versa) | Set --env staging or MEGAPORT_ENVIRONMENT=staging |
| Expired API key | Generate a new key pair in the portal |
| Stale config profile | Run megaport-cli config view to inspect the active profile |
# 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:
| Cause | Fix |
|---|---|
| Wrong environment — resource exists in staging but you're querying production | Check --env or MEGAPORT_ENVIRONMENT |
| Copied UID with extra whitespace or characters | Re-copy the UID from megaport-cli ports list --output json | jq -r '.[0].uid' |
| Resource was deleted | Add --include-inactive to list commands to see deleted resources |
| Looking at wrong resource type | Run megaport-cli ports list, vxc list, or mcr list for each resource type |
# 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
| Error pattern | Cause | Fix |
|---|---|---|
portSpeed must be one of | Invalid speed value | Ports: 1000, 10000, 100000. MCR: 1000, 2500, 5000, 10000, 25000, 50000, 100000 |
term must be one of | Invalid contract term | Valid terms: 1, 12, 24, 36 months |
vlan must be between 2 and 4093 | VLAN out of range | Use 0 (auto), -1 (untagged), or 2–4093 |
name exceeds maximum length | Name too long | Max 64 characters for ports and MVE |
marketPlaceVisibility is required | Missing required field on port buy | Always include "marketPlaceVisibility": false in port JSON |
connectType is required | Missing VXC partner config field | Include connectType in bEndPartnerConfig |
# 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
| Issue | Cause | Fix |
|---|---|---|
| Partner port full | The cloud provider's port is at capacity | Use megaport-cli partners list to find an alternative port |
| Invalid partner config | Wrong connectType, missing required field | Check the VXC partner configs reference |
| VLAN conflict | VLAN already in use on the port | Use megaport-cli ports check-vlan <portUID> to find available VLANs, or set "aEndVlan": 0 to auto-assign |
| AWS account ID format | Non-numeric or wrong length | Must be exactly 12 digits |
| IBM account ID format | Wrong format | Must be exactly 32 hex characters |
| Azure service key not found | Service key from wrong region or subscription | Re-copy from Azure Portal → ExpressRoute circuit → Overview |
# Check VLAN availability
megaport-cli ports check-vlan <portUID>
# 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 ~32 MB. It loads on page render — 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:
| Command | Reason |
|---|---|
--interactive / -i mode | Requires a TTY — not available in WebAssembly |
config subcommands | No filesystem access in browser sandbox |
Shell piping ( | jq) | No shell — commands run directly in WASM |
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.
Getting help
Built-in help
Every command has a --help flag:
megaport-cli --help
megaport-cli ports --help
megaport-cli ports buy --help
Verbose output
Add --verbose to any command to see the raw API request and response:
megaport-cli ports list --verbose
Useful for diagnosing API-level errors or understanding what the CLI is sending.
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