# Troubleshooting

> Recover from Oyster startup problems, missing terminal dependencies, model connection failures and hosted funding errors without deleting your work.

Choose the section for the place you are using: the local Oyster trial, the
Shiitake terminal, or hosted Fungi. They have different sign-in and funding
requirements.

## Oyster says port 8787 is in use

Leave the other server running and choose another port. From the directory
containing your trial project:

```sh
npx @fungi.computer/oyster try my-oyster --port 8788
```

Use the address printed by this run. A browser tab pointing at port 8787 will
still reach the other server.

## The browser did not open, or its sign-in link expired

Use the one-time link printed by the running trial. If it has already been used,
open `/login` at that trial's address and paste the owner key from
`my-oyster/.oyster-owner` into the sign-in form. Keep the key private.

If you passed `--no-open`, keeping the browser closed is expected.

## Trial startup stopped before the desktop was ready

Read the last phase and recovery command in the terminal. Check that Node is
version 24 or newer and Git is installed. If startup has not finished after five
minutes, press Ctrl-C in that terminal and keep the diagnostic path it printed.

Keep the project directory. After fixing the reported cause, restart from its
parent directory:

```sh
npx @fungi.computer/oyster try my-oyster
```

From inside `my-oyster`, use `npx @fungi.computer/oyster try` instead. Do not
delete the directory or stop unrelated services to retry. A desktop build
warning still needs attention; it is not a successful setup.

## Hello opens, but another App is not ready

The trial opens Hello first while Grove, Prints, Inkcap, Trellis, Bonsai and
Shed prepare in the background. Check the desktop's progress and the terminal
for a failed phase. Follow that phase's recovery command if it fails.

If you edited Hello and it no longer opens, keep its `main.js` script and commit
your changes before restarting. Oyster builds committed source. Follow the
[Hello edit recipe](/agents/build-an-app.md).

## Files are visible, but a command will not run

The trial can keep file access available when its Computer runtime fails to
start. Look for the Computer warning in the trial terminal, fix that reported
runtime problem, then restart the same project. Seeing files alone does not
prove the shell is ready.

In Grove, also check which Computer is attached to the Agent. An Agent created
with **No Computer** can converse but has no Computer for file or shell work.

## An Agent cannot answer, or Prints cannot generate an image

An installed App does not supply model access. Connect a model for Grove and
check the provider's error if a request is refused. A saved credential does not
prove that the provider accepts it or that its account has credit.

Prints image generation requires a deployed Oyster with Workers AI configured;
the local trial alone does not provide that service. See
[deploying Oyster](/guides/run-your-own-oyster#deploy-it).

## The terminal cannot find `fungi`

Spore installs that command. If you have not installed it, follow
[Install Shiitake](/install). Otherwise, check that npm's global executable
directory is on your PATH, open a new terminal and run:

```sh
fungi --version
```

If the launcher reports missing native dependencies, reinstall with optional
dependencies enabled:

```sh
npm install -g @fungi.computer/spore --include=optional
```

On Apple Silicon, use arm64 Node rather than x64 Node under Rosetta. Windows and
Alpine Linux are unsupported; see the full
[platform requirements](/install#install).

## `fungi doctor` passes, but the model still fails

Doctor checks the supported platform, saved Fungi sign-in, model configuration
and HTTP connectivity. It does not send a model prompt or check Team credit.
Inside the conversation, use `/model` to check the selected provider and model.
Signing in does not change the Session's model automatically.

Your provider key or subscription uses that provider's billing. Fungi hosted
models use the selected Team's billing. Follow
[terminal sign-in](/install#first-run) for the account you intend to use.

## An App asks for access, or an Agent is denied a tool

Read which resource and operation the request names before approving it. Check
that the App or Agent is working with the intended Team, Agent and Computer. Do
not grant broader access just to make an unrelated error disappear. The
[permissions guide](/guides/agent-sandbox-and-permissions) explains the
boundaries and approval flow.

## Hosted Fungi asks for credit or only shows the waitlist

Hosted signup is not open yet. An invite does not bypass the current waitlist;
use [Oyster locally](/oyster-quickstart) or the [terminal](/install) meanwhile.

Once hosted access is available, creating an account or adding your own model
key does not fund hosted Agents and Computers. Open **Your Teams** → **Billing**
for the Team you are using and check its available credit or Pro plan. Read
[Billing and credit](/account/billing) for what each covers.

## Before asking for help

Keep the installed version, operating system, exact command, failing step and
error text. For the Oyster trial, keep its diagnostic path and project folder.
Remove owner keys, provider tokens, sign-in links and private project content
from anything you share. Check [Fungi status](https://status.fungi.computer) for
hosted service health; a local startup failure may have a different cause.
