Skip to main content
Mirrored from Meerkat Meta main at 26f5ae9da1fd on 2026-11-03; Meta version 0.9.9 at that commit. Forge reports problems as messages in its terminal, in its pages, or in the terminal of an installed package. Most recovery actions keep your saved setups, private settings and installed state; prefer the action Forge offers over manual changes to its folders.

​
Starting Forge

​
A source checkout instead of a package

start.sh was run from a source checkout, which lacks the selected Meta SDK, guide gateway and Connect product. Download a release package and run bash start.sh in its extracted folder; see the quickstart.

​
Python is missing or too old

Install CPython 3.11 and select it, for example:
Use CPython 3.11 even when a newer Python is available: the application packages in the current release are built for it.

​
The existing environment uses the wrong Python

PYTHON_BIN does not upgrade an existing .venv. Forge stopped before changing anything. Move only .venv aside and start again with a supported Python; your saved setups stay in place:
If .venv.previous already exists, choose another unused backup name.

​
Python cannot create the environment

Or Pip could not be prepared in Forge's private .venv. Use a complete Python 3.11 installation with venv and ensurepip, for example one installed with uv python install 3.11, or python3.11 and python3.11-venv from the deadsnakes PPA on Ubuntu. If an incomplete .venv remains, move it aside as shown above, then retry with the command Forge printed.

​
Dependency preparation did not finish

The step name can also be installing the bundled SDKs, checking installed dependencies or checking the bundled product runtime. Read the error printed above this message and correct it; a download failure usually needs restored internet access. Keep .venv and your saved state in place, then run the retry command Forge printed. It keeps your Python, port, state folder and other settings, and --prepare-only if you used it.

​
The package is incomplete

Or The standalone SDK selection is missing. Unpack a fresh copy. Forge could not read a valid runtime or SDK selection from the extracted package. Verify the download again and extract it into a new folder.

​
A gateway override is set

Run unset MOBKIT_GATEWAY_BIN, then start Forge again.

​
The port is invalid or taken

Choose a valid port. If Forge is already running, reopen the address printed in its terminal instead of starting another copy. If port 8787 belongs to an unrelated application, start Forge on another port:
A different port changes the address, not the saved state.

​
The organization plugin does not load

An explicit META_FORGE_ORGANIZATION that is missing, ambiguous or invalid stops startup instead of falling back to the stock examples. Install the plugin into Forge’s own .venv, check its entry-point name and fields against the plugin contract, or unset the variable.

​
The SSH profiles are refused

The profile file and the files it names must be ordinary files owned by the user running Forge, with no group or other permissions, hard links or symlinks in their paths. Correct them while Forge is stopped, then restart it. See SSH profiles.

​
The guide and model providers

​
The guide needs a provider

When no model provider is available, the send button reads Connect your guide and opens provider setup without sending your idea. Open Guide settings, choose a provider, enter its key, choose Save locally, then Start guide. Saving does not test the key; the next guide message does.

​
The provider rejects the key

Wait for current work to finish. In Guide settings, choose Stop setup team and wait for the confirmed stop. Enter a replacement key for the same provider, choose Save locally, then Start guide. Return to the conversation and use its offered retry; the failed answer is not resent automatically.
The key comes from OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY in the environment Forge was started with, and such keys are read-only in the wizard. Stop Forge, change the variable and start Forge again from the same folder.

​
The setup team does not start

Forge shows Setup team could not start. Choose Retry setup team and wait for its status; this keeps your conversation and does not resend your answer. Check guide status reads the current state without starting anything. Related messages:
  • Connect the provider used by this saved setup team before starting it. The saved setup team uses another provider: configure that provider’s key.
  • Set MOBKIT_VISUALIZER_REASONING to low, medium or high. Correct or unset the variable and restart Forge.

​
A message is not confirmed

If Forge shows Conversation creation is not confirmed or Message delivery is not confirmed, choose Check saved conversation. Your writing and uploaded files stay available, and checking does not send the message again. After an interrupted guide response, choose Reload saved conversation. If Your submitted answer is saved appears, Retry saved answer deliberately resends that saved answer with its original files. If an attachment keeps uploading, choose Stop waiting, then Retry upload or Remove the files. Neither action sends your message.

​
Designs and packages

​
Package preparation is pending

Accepted design - package preparation pending means the plan needs a connection setup helper or a custom native tool bundle that the current installer cannot package yet. The design and its choices are saved, but new packages and builds wait for that support. Keep the design for later, or choose Revise with guide to discuss an explicit, reduced alternative. Enabling an optional Toolkit catalog or setup controller does not remove this limitation.

​
A model is not available to the agent team

The message names each unlisted provider and model, and some models the pinned release does list. Change the model of those classes, with the guide or in the Advanced editor, and export or install again.

​
The plan acceptance is not confirmed

If acceptance is waiting or cannot be confirmed, choose Check saved plan. It reads the saved conversation without accepting again. Try saving this plan again then deliberately saves the same reviewed plan.

​
Building applications

​
Application checks are unavailable

Forge never runs generated checks without isolation. On Linux, install the isolation prerequisites in the quickstart. On Ubuntu 24.04 and later, also load the bwrap-userns-restrict AppArmor profile; if /etc/apparmor.d already has a profile for /usr/bin/bwrap, reload that file with sudo apparmor_parser -r instead of adding a second one. Check the isolation before opening Forge:
A container host also needs a real PID 1 reaper, such as Docker’s --init, and an outer policy that lets bubblewrap create its namespaces and /proc.
Install the checker’s runtime libraries: on Debian and Ubuntu, libatomic1 and libstdc++6.
This computer cannot run application checks. Agent teams do not need them.

​
Preparation or a build seems stuck

  • Preparing… stays visible: choose Check preparation status. It reads the status without starting another download.
  • Build status is unavailable: choose Review build status, then Refresh build status. Your note and saved source are kept, and refreshing does not start a build.
  • Your saved build needs attention: Forge found source without a usable build selection. Choose Find your saved build, then Restore saved build for the build you want. This restores only the selection.
  • Stopping builder… or Closing build runtime…: wait for the existing build runtime to close. Retry cleanup retries it when offered; another build waits until cleanup is confirmed.

​
Installing and running

​
Forge runs another CPython

Forge refused before installing anything. Move .venv aside and restart Forge with CPython 3.11 as shown above.

​
The computer has another glibc

The Linux package’s application runtime supports exactly glibc 2.39. Use a Linux computer with that version, or a package whose runtime supports this computer.

​
A candidate can only update an existing installation

If Forge says This private runtime candidate is admitted only through the checked update of an existing stopped installation, this package cannot create a new installation. Keep the existing project folder and use its Stage accepted update or recovery controls. Do not extract the candidate into a new folder to work around the restriction.

​
Setup stays pending

Application setup is next means the application is installed but stopped, with no running agents or interface links yet. Choose Review private settings if required settings are missing, then Prepare application setup and Set up and start application when they are offered. If Setup pending remains, keep the same folder and saved settings. Check setup status only reads availability; saving private settings or connecting the guide does not supply a missing setup runtime.

​
Background mode is unavailable on macOS

Move the Forge folder and the installation folder to a folder such as ~/MetaForge, or run the application While Forge is open. A service installed in one of those folders earlier is not moved.

​
A start fails or the status is unclear

  • After a failed start, choose Stop and verify cleanup when offered and wait until Forge confirms that the installation is stopped. Then Change private settings, save the correction and start the same installation again.
  • Installation status is unavailable: choose Review installation status, then Check installation status. The saved receipt describes an earlier observation.
  • If an installation command reports an error, some of its work may already have finished. Wait for the checked status before choosing another action, and do not send another Stop just to clear the error.
  • A running application’s UI link is missing: choose Retry UI links.

​
The Console password is forgotten

For an installation on this computer, stop it in Forge and wait for cleanup. Choose Change private settings, enter a replacement Console password and choose Save private settings; blank fields keep their saved values. Start the same installation again and use its current Console link.

​
An update crosses into Meta 0.9.4

Meta 0.9.4 keeps sessions and identities in Core’s own stores and refuses a state folder that an earlier Meta release wrote and that was not migrated (NativeStorageMigrationRequired). Forge does not run that migration: it stages such an update as blocked and changes nothing. Back up the complete stopped project folder, including .mobkit/, and follow Upgrading to Meta 0.9.4.

​
Packages installed from a terminal

​
The project folder is writable by others

Run the non-recursive repair in the same project folder, then retry the same install command:

​
Installation stops

Correct the problem reported above it and run the printed retry command in the same folder. Keep .venv, .env, workspace, data and .mobkit in place. Install Python 3.11 or newer, then run this installer again. means the selected Python (PYTHON_BIN, default python3) was not found, and Python 3.11 or newer is required means it is too old.

​
Start refuses

Startup failures print Deployment needs attention: followed by the reason.

​
A package refuses its shell commands

The package is a custom application built on a selected Meta and Toolkit runtime. Install, set up, update and recover it only from its saved setup in Forge.
The cloud scripts of a package built for a local destination refuse. Change the plan’s destination with the guide and build the package again.

​
Google Cloud

If Forge says the Google Cloud CLI was not detected when it started, install it and sign in, then stop Forge normally and start it again from the same folder and state folder: installing the CLI does not update a running Forge. Stopping an application does not remove billed cloud resources. Review cloud removal names the original VM, disk and access rule; removing them permanently loses the disk’s data, and Forge makes no backup. Keep the original removal request and choose Recheck removal until all three are confirmed absent; until then, charges may continue.