Skip to content

Troubleshooting ​

Find your error by the message or symptom below. Before you ask for help at Contact, run ph forge doctor and include the output.

Not signed in to Tara ​

You hit this error when you see "not signed in to Tara", "Tara refused the request (401)", or a ✗ Tara line in ph forge doctor. The cause is that you aren't signed in, or the session expired. A browser sign-in session is fairly short, about 12 hours, to protect actions that need high privileges. Sign in again like this:

bash
ph login                 # opens the browser, click Allow
ph tara whoami           # prints the account, organization and the session expiry

A login belongs to one organization. If you are in several, ph login asks you to pick one from a numbered list, or you can pass ph login --org <slug> (required when there is no terminal, such as in CI). If you belong to none yet, the command prints the Portal address <tara>/get-started where you create an organization or accept an invitation. Switch later with ph org switch <slug>.

If your machine has no browser, such as over SSH or in CI, create a personal token in the Tara Portal (account menu, Access tokens), run ph tara login --token-stdin, and paste the token.

If you can't connect to Tara, check that the address starts with https://, then check your network or VPN.

You don't belong to an organization yet (no_org) ​

You see "you do not belong to any organization yet", or the code no_org (HTTP 409), when you run ph login or create a token. The cause is that your account is signed in but isn't a member of any organization. Signing in only proves who you are. Nothing is lost: the sign-in code isn't used up, so you can run the command again afterward.

On the Portal: open <tara>/get-started. Either create an organization (a name and a slug such as acme, and you become its Owner), or open the invitation link an Owner or Admin sent you.

With Phillip: create one with ph org create acme (it needs a browser login), or accept an invitation in the Portal first. Then sign in again:

bash
ph org create acme --name "Acme Inc."
ph login

Choose an organization first (org_required) ​

You see "Choose an organization first", or the code org_required (HTTP 409). The cause is that you belong to several organizations and the login didn't say which one. In a terminal, ph login shows a numbered list. Without a terminal, such as in CI or over SSH, it prints the list and stops, because it can't ask you.

With Phillip: name the organization.

bash
ph org list                # the organizations you belong to
ph login --org acme

In CI, set PHILLIP_ORG=acme next to PHILLIP_TARA_TOKEN. On the Portal: pick the organization in the switcher at the top.

No free seat (seat_limit) ​

You see seat_limit (HTTP 409) when you invite someone, accept an invitation, or change a role. The cause is that the organization has used all its seats. Owners, Admins, and Members each use a seat, and the Free plan has 7. Viewers don't use a seat. The Team plan has no seat limit: an Owner can upgrade.

An Owner or Admin can fix it in one of these ways:

  • On the Portal: open the organization's members page. Remove people who left, or change someone who only needs the browser (a BA, PO, or PM) to Viewer. Invite new BAs, POs, and PMs as Viewers.
  • With Phillip:
bash
ph org current                          # plan and seats used
ph org members                          # who is in the organization
ph org members set-role <login> viewer  # free a seat
ph org members remove <login>
ph org invite <email> --role viewer

If you aren't an Owner or Admin, ask one of them to do it.

The name exists only in another organization ​

You see "did you mean beta/skill-foo?", or the code not_found_hint (HTTP 404), when you install or lock a resource by a bare name. The cause is that nothing named skill-foo exists in the official store or in your own organization, but another organization has a public community resource with that name. A bare name never matches another organization's resource, on purpose, so nobody can take over a name. The message lists up to five full names.

Use the full name <org>/<name>. On the Portal: the community store shows each resource's full name. With Phillip:

bash
ph tara search skill-foo --channel community
ph tara add beta/skill-foo

If a dependency in a manifest triggers the error, write the full name in dependencies. A community resource asks for confirmation before it's added.

404 when you open an organization ​

You open <tara>/acme/... or run a command for an organization and get 404 Not found. The cause is that you aren't a member of that organization, or its slug is misspelled. Tara answers the same 404 for both, so that people outside an organization can't tell whether it exists.

  1. Run ph org list or check the organization switcher to see the slugs you belong to.
  2. If you should be a member, ask an Owner or Admin to invite you, then accept the invitation.
  3. If you're a member, switch to it with ph org switch <slug>, because your login and token may belong to another organization.

The ph command isn't found (PATH) ​

This error appears as ph: command not found, or the VS Code integrated terminal says it can't find ph, or the VS Code extension says Phillip isn't installed even though you installed it. The reason is that npm install -g puts ph in npm's bin directory, and that directory isn't in your PATH. VS Code opened from the Dock or the Start menu also often has a more minimal PATH than your terminal.

  1. Open a new terminal, because the shell reads its configuration again only at startup.

  2. Find the directory to add:

    bash
    echo "$(npm prefix -g)/bin"
  3. Add that directory to PATH in your shell configuration file. For example, with zsh:

    bash
    echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
  4. For VS Code, quit it completely and reopen it from a terminal with code ., or run ph setup so the extension picks up the path.

On Windows, add the directory that npm prefix -g prints to the user's Path variable, then reopen PowerShell.

If you get EACCES during installation, npm is installing into a system directory where you have no write permission. The install script doesn't use sudo on its own, so point npm at a directory of your own:

bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Then run the install command again.

Node older than 22 ​

When you see "Node v… is too old. Phillip needs Node 22 or later", or a ✗ Node line in ph forge doctor, upgrade Node to 22 or later and run the install command again.

bash
node --version           # needs v22 or later
nvm install 22 && nvm use 22   # if you use nvm; or fnm, brew install node, the installer from nodejs.org

If your machine has several Node versions, make sure the terminal and VS Code use the same version 22.

Blocked by Guardrails ​

When an action by the agent is refused or asked about, the message includes the rule name and the reason. A block doesn't always mean you did something wrong, because sometimes a rule blocks by mistake. Read the message to see which rule and why, then try asking the agent to take another safe approach to the same goal.

If you believe the rule blocked by mistake, send feedback with your reason so the owning team can review it. Phillip masks secrets in the note before it sends.

bash
ph guardrails feedback <rule id> --note "Why I think this is a false positive"

To see Guardrails status on your machine, run ph guardrails status. Don't try to turn Guardrails off. If you need an exception, ask your organization's Owner or Admin, or your project admin, so the policy is updated through the proper process. See also When Guardrails blocks you.

Plugin has a bad signature or was yanked ​

There are three signs. First, the message "the signature of … is invalid" or "… has no signature" when you install a resource or run ph bandum ui. Second, the warning "no Tara signing key is configured, so only sha256 is checked" (package signatures weren't verified). Third, ph tara list or ph forge doctor reports that a resource is yanked or deprecated.

SymptomWhat to do
The signature is wrong or missingDon't run this package and tell your Owner or Admin. Check the trusted keys with ph tara keys
The warning that the signature wasn't verifiedYour machine has no public key. Get the key from your Owner or Admin, then run ph tara keys trust ed25519:<key>
A resource is yankedThis package has a safety problem. Run ph tara outdated, then ph tara upgrade to move to a version that isn't yanked, then commit phillip.lock
The scm plugin reports no connector plugin for <host>Run ph connect to choose a provider for that host

Signing and revocation explains this mechanism.

Errors when you connect GitHub or GitLab ​

You seeWhat to do
401 or 403 when you verify the tokenThe token is wrong, expired, or lacks permission, or you aren't a Developer on the repo. Create it again with ph connect
404You can't reach the host or the project. Check --host and check that the token has access to the project
The new token has no effectThe GITHUB_TOKEN or GITLAB_TOKEN environment variable overrides the saved token. Remove them from your shell

Errors when you run Bandum on your machine ​

You seeWhat to do
"port … is busy"Drop --port so Phillip picks a free port
"--docker needs Docker installed and running"Start Docker Desktop and run again, or drop --docker to use SQLite
"Bandum exited early"Read the 20 log lines Phillip prints with it, and run ph bandum ui logs
Bandum reports 401 from GitHub or GitLabRun ph connect, then ph bandum ui stop, then run ph bandum ui again

Everyday task errors ​

You seeWhat to do
no open PR for GH-12You haven't opened a PR, or the branch doesn't carry the id GH-12
branch ... does not have the latest commit pushedRun git push -u origin HEAD, then run the command again
ph bandum check exits with code 2Fix each error line. Warnings don't block
The repo has no .bandum.jsonThe project hasn't declared how to run the app. Use --cli or ask the dev

Warning lines in ph forge doctor ​

A ⚠ line is optional and doesn't make setup fail.

ph forge doctorNode         v24.22.0Claude Code  2.1.308 (Claude Code)git          git version 2.50.1 (Apple Git-155)Tara         maya.chen @ https://tara.phillipcli.cloudphillip.lock 17 resources locked (lock ba8972f416dd)Ryoma        https://ryoma.phillipcli.cloud: metrics receivedCollector    data received through RyomaGuardrails   not installed on this machine (the Guardrails dashboard will be empty). Install: sudo "$(command -v ph)" guardrails install --tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:<public key>
You seeMeaning
⚠ RyomaThe session hasn't sent metrics, or you aren't signed in to Tara. Sign in again. If it still reports this, ask the operations team
⚠ GuardrailsYour machine doesn't have Guardrails installed. Run the exact sudo … command that doctor prints, or ask whether you're required to install it
⚠ CollectorThe collector isn't receiving data, so the dashboard is empty. Ask the operations team to check