Skip to content

Troubleshooting

When something doesn't work, walk down this list before opening a GitHub issue. Most problems we see during early-adopter onboarding fall into one of these buckets.

Connection issues

My MCP client says the mesa server is unreachable

Check that the URL is correct and that your network allows outbound HTTPS to mesa-mcp.cis240692.projects.jetstream-cloud.org. The hosted instance is on Jetstream-2 and behind nginx + Let's Encrypt; some corporate networks block *.jetstream-cloud.org.

Test with curl: 

curl -fsS https://mesa-mcp.cis240692.projects.jetstream-cloud.org/healthz

I get a 401 after a few hours

Bearer tokens issued through CyVerse Keycloak expire. Most MCP clients refresh automatically; if yours doesn't, restart the client. If that still fails, clear the cached token in your client's config directory.

My local mesa-mcp subprocess starts and immediately exits

Run it manually from a terminal with the exact arguments your client would pass, and read the stderr output:

mesa-mcp --config /path/to/config.yaml

The most common causes are: missing config.yaml, wrong Python version (< 3.11), or a broken venv. Reinstall into a fresh venv.

Authentication issues

iRODS authentication fails with the right username/password

Confirm zone and host:

  • irods_host: data.cyverse.org
  • irods_port: 1247
  • irods_zone_name: iplant

If you recently changed your CyVerse password, it can take a few minutes for the new password to propagate to iRODS.

Permission issues

ds_write_file returns "permission denied" on a path I own

Check the iRODS ACLs on the parent collection — write permission has to be inherited or granted explicitly.

ds_list_directory_details /iplant/home/you/myproj

Look for own or write in the acl field for your username.

Metadata issues

An AVU I added doesn't appear in get_avu_history

The history catalog only records AVUs added through MESA tools. Direct imeta CLI calls bypass it. If you need a fresh sync, ask your project admin to run the mesa-ducklake reconcile job.

Discovery Environment issues

formation-mcp launch_app returns "no allocation"

The CyVerse DE allocation that backs your formation-mcp token has been exhausted or revoked. Contact your CyVerse PI or the MESA team.

When to open an issue

If you've worked through the relevant section above and still see the problem, open an issue against the right repo:

Please include: client name + version, MCP server version, the exact prompt, and the full stderr / log output.