Troubleshoot Agent Fabric CLI Errors

Name: projectDescriptorNotFound

What it means: exchange.json is missing for the project.

How to fix: Run the command from the project root and confirm that exchange.json exists.

Name: invalidAgentNetworkProject

What it means: The project failed validation.

How to fix: Check the validation output printed before the error. Fix the reported issue and rebuild.

Name: buildAssetsError

What it means: An asset failed to build.

How to fix: Read the nested cause. The cause is usually a malformed asset file in the assets directory.

Name: variableNotFound

What it means: A ${placeholder} has no matching variable.

How to fix: Declare the variable under metadata.variables in exchange.json.

Name: validatingAgentNetworkError

What it means: Project validation exited with a non-zero status.

How to fix: Review the validator output for the specific failure.

Name: buildingAgentNetworkError

What it means: The build process exited with a non-zero status.

How to fix: Check the build logs printed before the error.

Name: wrapperNotFoundError

What it means: The Maven wrapper (mvnw/mvnw.cmd) is missing.

How to fix: Confirm that the project is a Maven project and that the wrapper is present and executable.

Name: buildBrokersAppError

What it means: The Brokers App failed to build.

How to fix: Check the logs. The cause is usually an AgentScript compile error.

Name: variablesNotFound

What it means: Multiple `${placeholder}`s are unresolved.

How to fix: Declare each listed variable under metadata.variables in exchange.json.

Name: invalidVariablePath

What it means: A variable resolves to an invalid nested path.

How to fix: Correct the variable path in exchange.json.

Name: invalidPath

What it means: A file or YAML path is invalid.

How to fix: Verify the referenced path exists and is well-formed.

Name: invalidOrNotBuiltAgentNetworkProject

What it means: A downstream command ran before the project was built.

How to fix: Run agent-network project build first.

Name: unsupportedSchemaVersion

What it means: The schemaVersion isn’t supported by this CLI.

How to fix: Use a supported version listed in the message or upgrade the CLI.

Name: validationConnectionsError

What it means: A connection references an undefined target or has the wrong kind.

How to fix: Fix the connection references in agent-network.yaml to match defined entities and kinds.

Name: noBrokerForImplementation

What it means: An AgentScript implementation has no matching broker entry.

How to fix: Add a broker for the implementation or remove the orphaned file.

Name: unsupportedToolType

What it means: An entity declares an unknown tool type.

How to fix: Use a supported tool type (listed in the message).

Name: invalidAgentScriptPath

What it means: An AgentScript path is invalid or its content is unsafe.

How to fix: Use a path inside the project and remove unsafe content.

Name: errorParsingAgentFile

What it means: An AgentScript file failed to parse.

How to fix: Fix the syntax error reported in the nested cause.

Name: policyBindingNotFound

What it means: A referenced policy binding doesn’t exist.

How to fix: Define the binding or correct the reference name.

Name: brokerKindMismatch see note

What it means: A broker’s kind doesn’t support the requested interface kind.

How to fix: Align the broker’s kind with the interface or use a compatible broker.

Name: brokerIdMismatch see note

What it means: The broker id in AgentScript doesn’t match the YAML.

How to fix: Make the broker id consistent between AgentScript and agent-network.yaml.

Name: invalidAgentNetworkProjectDescriptor see note

What it means: exchange.json descriptor is malformed.

How to fix: Fix the descriptor per the details in the message.

Name: brokerSupportedInterfacesUrlMismatch see note

What it means: A broker’s A2A supported interfaces use different base URLs.

How to fix: Use the same scheme, host, and port for all supported interfaces. Use different paths only.

Name: brokerUnsupportedProtocolBinding see note

What it means: A broker’s protocolBinding isn’t supported.

How to fix: Use a supported protocolBinding value (listed in the message).

Name: mcpMainYamlNotFound see note

What it means: MCP introspection can’t find the main YAML.

How to fix: Set the main field in exchange.json to the correct file.

Name: mcpYamlParseError see note

What it means: The MCP YAML failed to parse.

How to fix: Fix the YAML syntax error in the reported file.

Name: mcpServerJsonNotFound see note

What it means: server.json couldn’t be read.

How to fix: Confirm server.json exists and is readable.

Name: mcpServerJsonInvalidJson see note

What it means: server.json isn’t valid JSON.

How to fix: Fix the JSON syntax.

Name: mcpServerJsonSchemaValidation see note

What it means: server.json failed schema validation.

How to fix: Correct the fields listed in the message.

Name: mcpServerJsonNoRemotes

What it means: server.json defines no remotes.

How to fix: Add a remote entry. Only remote MCP servers are supported.

Name: mcpServerJsonMultipleRemotes

What it means: server.json defines multiple remotes.

How to fix: Pass --transport to select one.

Name: mcpServerJsonRemoteNotFound

What it means: The requested transport isn’t in server.json.

How to fix: Use one of the available transports listed in the message.

Name: mcpInvalidRemoteProtocol

What it means: The remote URL uses an unsupported scheme.

How to fix: Use http: or https:.

Name: mcpInvalidRemoteUrl

What it means: The remote URL failed to parse.

How to fix: Correct the URL in server.json.

Name: mcpInvalidRegistryKey

What it means: A registry key contains invalid characters.

How to fix: Use only lowercase letters, digits, and hyphens.

Name: mcpCannotDeriveRegistryKey

What it means: A registry key couldn’t be derived.

How to fix: Declare an explicit registry key.

Name: assetIdTooLongForDeployment

What it means: The project asset id exceeds the deployment-name length limit.

How to fix: Shorten the asset id and rebuild.

Name: invalidExchangeJson

What it means: exchange.json isn’t valid JSON.

How to fix: Fix the JSON syntax.

Name: invalidExchangeJsonField

What it means: An exchange.json field has the wrong type.

How to fix: Set the reported field to the expected type (a string).

Name: pushNotificationNotSupported

What it means: A broker sets capabilities.pushNotifications: true in its A2A card, but push notifications aren’t supported.

How to fix: Set pushNotifications to false in interfaces.a2a.card and rebuild.

Name: variableKeyCollision

What it means: Two metadata.variables entries in exchange.json flatten to the same dotted key.

How to fix: Rename one entry, or use nested objects consistently.

Name: variableNameContainsColon

What it means: A metadata.variables key or category in exchange.json contains the restricted : character.

How to fix: Remove the : from the reported key or category.

Name: unsupportedAuthenticationKind

What it means: A connection or card.authentication declares an authentication kind that the CLI doesn’t recognize.

How to fix: Use a supported authentication kind and rebuild.

Name: a2aInterfacesNotSupportedForV03

What it means: interfaces was declared on a connection to an A2A v0.3 agent.

How to fix: Remove interfaces from the A2A v0.3 connection, or point the connection to an A2A v1 agent.

Name: invalidA2aInterfaceBasePath

What it means: An interfaces.*.basePath value failed validation.

How to fix: Use an absolute path starting with /, without .. segments, mid-path empty segments (//), or URL schemes.

Name: invalidA2aInterfaceProtocol

What it means: An interfaces binding key isn’t a supported protocol.

How to fix: Use only jsonrpc, http, or grpc as binding keys under interfaces.

Name: invalidA2aInterfacesShape

What it means: interfaces, an interfaces binding, or a card policy’s interfacePaths isn’t a plain object.

How to fix: Use plain objects for interfaces, its bindings, and interfacePaths.

Name: javaHomeNotSet

What it means: JAVA_HOME isn’t set. Schema 1.0.0 builds require a JDK to generate the Brokers application.

How to fix: Set JAVA_HOME to the installation directory of a supported JDK.

Name: javaExecutableError

What it means: The Java executable under JAVA_HOME couldn’t be launched.

How to fix: Point JAVA_HOME to a valid JDK installation that contains bin/java.

Name: organizationAccessError

What it means: You lack access to the project’s groupId.

How to fix: Switch to an org that owns the groupId or request access.

Name: projectNotBuiltError

What it means: Publish ran before build.

How to fix: Run agent-network project build first.

Name: publishError

What it means: An asset failed to publish.

How to fix: Read the nested cause. See Exchange.

Name: assetNotFoundError

What it means: An Exchange asset lookup failed.

How to fix: Verify the GAV, confirm that the asset exists, and check org access.

Name: assetTypeMismatchError

What it means: An asset already exists in Exchange with a different type.

How to fix: Use a new asset id or version, or reconcile the existing asset’s type.

Name: ownershipConflictsError

What it means: The asset id is already owned by another project.

How to fix: Choose a different asset id or publish from the owning project.

Name: deployedResourcesExistOnUnpublish

What it means: Unpublish is blocked because deployed resources still reference the assets.

How to fix: Run agent-network project undeploy first, then retry unpublish.

Name: unpublishError

What it means: Reports a failure that occurred during the unpublish stage.

How to fix: Read the nested cause for the specific reason. See Exchange for the known 403 issue.

Name: incompatibleTargetVersionPublish

What it means: The target/ artifact was built with an incompatible CLI version.

How to fix: Rebuild with the current CLI version, then publish.

Name: projectNotBuiltPublish

What it means: No build artifact was found at publish time.

How to fix: Run agent-network project build first.

Name: publicationAggregateFailure

What it means: One or more publish tasks failed. This error consolidates the failures.

How to fix: Read the logs for each sub-failure. Each sub-failure maps to an error-code or dependent-service entry on this page.

Name: unrecognizedComponentKindForPublicationOrder

What it means: Internal: a component kind wasn’t recognized when ordering publication.

How to fix: Rebuild the project. If the error persists, then report it with the requestId.

Name: metadataPatchParseFailed

What it means: Internal: a serialized metadata file couldn’t be parsed for version patching.

How to fix: Rebuild the project. If the error persists, then report it with the requestId.

Name: createApiError

What it means: Creating an API instance in API Manager failed.

How to fix: A 409 often means that an instance with this name already exists. See API Manager.

Name: deployError

What it means: Deploying an API into a gateway failed.

How to fix: Read the nested cause. See Runtime Fabric / AMC.

Name: connectionNotFoundError

What it means: A connection couldn’t be resolved.

How to fix: Verify the connection is published and its name matches the reference.

Name: gettingEgressConnectionError

What it means: Fetching the egress connection failed.

How to fix: Check the egress gateway and target. See Gateway Manager.

Name: deployAPIError

What it means: A generic API deploy failure.

How to fix: Read the nested cause.

Name: brokerGroupDeploymentError

What it means: Broker group (Agent Graph) deployment failed.

How to fix: Check the logs. See Runtime Fabric / AMC.

Name: unableToResolve

What it means: A GAV couldn’t be resolved at deploy time.

How to fix: Build and publish the project before deploying.

Name: createPatchApiError

What it means: Updating an existing API instance failed.

How to fix: Read the nested cause. See API Manager.

Name: noTranscodingFoundFor

What it means: An expected transcoding policy is missing.

How to fix: Verify that the transcoding policy is published and referenced correctly.

Name: gatewayTargetSpaceError

What it means: The ingress and egress gateways don’t match the runtime target space.

How to fix: Choose gateways whose target space matches your runtime target.

Name: createApiSpecNotFound

What it means: The API spec asset isn’t in Exchange.

How to fix: Publish the Agent Network before deploying.

Name: requestTimeout

What it means: A single HTTP request timed out.

How to fix: Retry the request. If the error persists, then increase --request-timeout. See retry engine.

Name: commandTimeout

What it means: The overall command exceeded its timeout budget.

How to fix: Review org resource limits and increase --process-timeout. Check steps for the command’s progress.

kubectl get events -n <namespace> --sort-by='.lastTimestamp'
kubectl describe resourcequota -n <namespace>

oc get events -n <namespace> --sort-by='.lastTimestamp'
oc describe resourcequota -n <namespace>

Name: findingAssetsError

What it means: Discovering assets to deploy failed.

How to fix: Retry the request. If the error persists, then read the nested cause.

Name: nonPublishedAssetsFoundError

What it means: One or more assets aren’t published in Exchange.

How to fix: Publish the listed assets, then deploy.

Name: noGatewayFoundForInstance

What it means: No gateway resolvable for an API instance.

How to fix: Verify that a gateway is configured for the instance’s protection direction.

Name: assetNotFoundForInstance

What it means: An API instance’s backing asset is missing from Exchange.

How to fix: Publish the asset before deploying.

Name: assetNotFoundForConnection

What it means: A connection’s backing asset is missing from Exchange.

How to fix: Publish the asset before deploying.

Name: missingRequiredUpstreamUrl

What it means: A required upstream URL wasn’t resolved.

How to fix: Provide the upstream URL variable at deploy time (--property).

Name: dependencyFailure

What it means: A stage was skipped because a dependency’s stage failed.

How to fix: Fix the upstream failure reported elsewhere in the output.

Name: apiBelongsToAnotherProject

What it means: An instance name collides with another project’s instance.

How to fix: Choose a different name or reuse the existing instance.

Name: invalidSourceValue

What it means: An invalid source value was supplied.

How to fix: Set source to a supported value (listed in the message).

Name: agentGraphDeploymentError

What it means: Agent Graph provisioning failed.

How to fix: Check the logs. See Runtime Fabric / AMC.

Name: connectionRefNotFoundError

What it means: A connection.ref.name didn’t resolve.

How to fix: Verify the connection is published and the ref name matches.

Name: undeployError

What it means: Reports a failure that occurred during the undeploy stage (fail-closed).

How to fix: Read the nested cause for the specific reason. See Dependent Services: Status Codes and Common Issues.

Name: invalidPolicy

What it means: A policy metadata response was empty or invalid.

How to fix: Verify the policy GAV (groupId:assetId:version coordinate) and retry the request. The error can be transient. See API Manager.

Name: missingGatewayForSharedSpace

What it means: A shared-space deploy needs a gateway but none was given.

How to fix: Provide a gateway with --gateway.

Name: invalidGAVFormat

What it means: A GAV argument couldn’t be parsed.

How to fix: Use groupId:assetId:version.

Name: parentAssetNotFound

What it means: A parent asset lookup failed.

How to fix: Verify the parent asset exists in Exchange.

Name: invalidAgentProtocol

What it means: Agent metadata declares no protocol for a connection.

How to fix: Declare a protocol for the connection in agent metadata.

Name: unsupportedAgentProtocol

What it means: An agent exposes a non-A2A protocol only.

How to fix: Connect only A2A (Agent2Agent) agents that use a2a or a2a_v1.

Name: networkLockMissing

What it means: The Agent Network lock file generated at publish time is missing during deployment.

How to fix: Build and publish the Agent Network to regenerate the lock file, then deploy.

Name: networkLockMalformed

What it means: The Agent Network lock file is malformed or has an invalid key.

How to fix: Rebuild and republish the Agent Network to regenerate the lock file, then deploy.

Name: assetMissingFromNetworkLock

What it means: An asset referenced by the project isn’t in the lock file.

How to fix: Rebuild and republish the Agent Network so the lock file includes every asset, then deploy.

Name: incompatibleTargetVersionDeploy

What it means: The target/ artifact was built with an incompatible CLI version.

How to fix: Rebuild with the current CLI, republish, then deploy.

Name: projectNotBuiltDeploy

What it means: Deploy ran before build.

How to fix: Run agent-network project build first.

Name: bulkApplyPolicyError

What it means: Applying policies in API Manager failed.

How to fix: Check policy GAV resolution and org entitlements. See API Manager.

Name: brokerAuthorizationPolicyConflict

What it means: An explicit user-context-propagation policy conflicts with the broker’s authorization section.

How to fix: Align or remove the conflicting policy field, per the message.

Name: deploymentSettingsFlagsMutuallyExclusive

What it means: --deployment-properties-file and --deployment-property were both passed.

How to fix: Use one or the other, not both.

Name: deploymentFileReadError

What it means: The deployment settings file couldn’t be read.

How to fix: Verify the file path and permissions.

Name: deploymentSettingsMalformedEntry

What it means: A --deployment-property entry is malformed.

How to fix: Use <scope>:<name>:<value> (for example brokers:vCores:0.1).

Name: deploymentSettingsInvalid

What it means: Deployment settings failed semantic validation.

How to fix: Fix the reported setting.

Name: runtimeVersionNotFound

What it means: The requested runtime version isn’t available.

How to fix: Use one of the available versions listed in the message.

Name: mixedRuntimeTypesInDeploy

What it means: The deploy set mixes Mule apps and Agent Graphs.

How to fix: Split into separate deploys.

Name: deploymentAggregateFailure

What it means: One or more deploy tasks failed. This error consolidates the failures.

How to fix: Read the logs for each sub-failure. Each sub-failure maps to an error-code or dependent-service entry on this page.

Name: runtimeVersionNotResolved

What it means: Internal: runtime version wasn’t resolved before deployment.

How to fix: Rebuild and redeploy. If the error persists, then report it with the requestId.

Name: undeployEnvironmentIdRequired

What it means: --gav undeploy is missing the environment id.

How to fix: Pass --environment.

Name: undeployEnvironmentRequired

What it means: No environment was selected for undeploy.

How to fix: Pass --environment.

Name: publicationBeforeDeploymentFailed

What it means: The auto-publish step before deploy failed, so deploy aborted.

How to fix: Fix the publish failure. See the embedded cause and Publish Errors.

Name: llmAuthenticationKindNotSupported

What it means: An LLM connection’s authentication kind isn’t declared by the referenced LLM metadata.

How to fix: Use a supported kind listed in the message, or publish an LLM asset that declares the kind.

Name: llmAssetRequiresV2

What it means: A V1 Agent Network references an LLM asset that declares inputFormat, which requires V2.

How to fix: Migrate the project to schema 2.0.0, or reference an LLM asset without inputFormat.

Name: llmInputFormatRequiresAuthentication

What it means: An LLM asset declares inputFormat but has no nonempty authentication.

How to fix: Add authentication to the LLM metadata and republish the asset.

Name: llmModelNotDeclared

What it means: An agent requests a model that the referenced LLM asset doesn’t declare.

How to fix: Use a declared model ID, or add the model to the LLM asset and republish it.

Name: llmAuthenticationKindUnmapped

What it means: The referenced LLM metadata declares the connection’s authentication kind, but the CLI has no policy mapping for it.

How to fix: Use one of the kinds listed in the message, or upgrade the CLI.

Name: llmAdapterPolicyNotFound

What it means: The adapter policy named by the LLM asset’s policyRef wasn’t found in Exchange.

How to fix: Republish the LLM asset with a valid policyRef, or publish the adapter policy.

Name: llmAdapterPolicyLookupFailed

What it means: Resolving the LLM asset’s adapter policy failed.

How to fix: Retry. If the error persists, then check Exchange availability and your access to the policy.

Name: cardAuthenticationUpstreamsError

What it means: Configuring dual egress upstreams for agent-card authentication failed in API Manager.

How to fix: Confirm that Flex Gateway is version 1.5.0 or later, the connection uses a2a or a2a_v1, and outbound policies are enabled for the environment. Read the nested cause.

Name: outboundPolicyUpstreamLabelNotFound

What it means: An outbound policy was bound to a labeled upstream (agent or card) that API Manager didn’t return.

How to fix: Redeploy so upstreams and routing match the desired set. If the error persists, then open a support case with the requestId.

Name: noDomainsFound

What it means: No private-network domains for the target space.

How to fix: Create a private network in the target space first.

Name: setupIngressGatewayError

What it means: Ingress gateway setup threw.

How to fix: Read the nested cause. See Gateway Manager.

Name: setupIngressGatewayFail

What it means: Ingress gateway setup returned a non-success status.

How to fix: Check the status and response in the message. See Gateway Manager.

Name: setupEgressGatewayError

What it means: Egress gateway setup threw.

How to fix: Read the nested cause. See Gateway Manager.

Name: setupEgressGatewayFail

What it means: Egress gateway setup returned a non-success status.

How to fix: Check the status and response. See Gateway Manager.

Name: gatewayNotFoundError

What it means: A named gateway isn’t in the environment.

How to fix: Use one of the available gateways listed in the message.

Name: runtimeTargetNotFoundError

What it means: A named runtime target space isn’t in the environment.

How to fix: Use an available space or create one (CloudHub 2 docs).

Name: unableToRetrieveTargetSpaceMetadata

What it means: Fetching target space metadata failed.

How to fix: Retry the request. See Gateway Manager.

Name: unableToRetrieveGateways

What it means: Fetching the gateway list failed.

How to fix: Retry the request and check org and environment access.

Name: unableToRetrieveGatewayVersions

What it means: Fetching gateway versions failed.

How to fix: Retry the request. See Gateway Manager.

Name: gatewayChannelNotFoundError

What it means: The requested update channel doesn’t exist.

How to fix: Use one of the available channels listed in the message.

Name: noGatewayVersionsFoundError

What it means: The channel has no versions.

How to fix: Choose a different channel.

Name: gatewayAlreadyExists

What it means: A gateway with this name already exists in the environment.

How to fix: Choose a different name because gateway names are unique per environment.

Name: setupGatewayInsufficientResourcesError

What it means: The org’s gateway quota is exhausted.

How to fix: Delete an unused gateway or increase your org limits.

Name: missingDomainsResponse

What it means: Domains are required for a non-shared target but none were returned.

How to fix: Confirm a private network exists for the target.

Name: gatewayUpdateFailedError

What it means: Updating the gateway runtime version failed.

How to fix: Check the status in the message and retry the request.

Name: gatewayUpdateTimedOutError

What it means: The gateway update didn’t finish within the timeout.

How to fix: Check the gateway status in Runtime Manager. Retry when the gateway is stable.

Name: noEntitlementForOrganization

What it means: Retrieving org entitlements failed.

How to fix: Check the status in the message and verify org access. See Access Management.

Name: organizationAccessDenied

What it means: You lack access to the org.

How to fix: Switch orgs or request access.

Name: selectedOrganizationMismatch

What it means: The groupId doesn’t match the selected org.

How to fix: Switch to the org that owns the assets.

Name: downloadFileError

What it means: A dependency download failed.

How to fix: Check network access and retry the request.

Name: couldNotFindVersion

What it means: No resolvable version in maven-metadata.xml.

How to fix: Confirm the dependency exists in the repository and that you have network access to it.

Name: invalidStrategyVersion

What it means: A dependency strategy or version config is invalid.

How to fix: Correct the strategy or version in the descriptor.

Name: invalidMetadataFile

What it means: A dependency metadata file is invalid.

How to fix: Rerun setup to refresh the cached dependency.

Name: runtimeDependenciesFileNotFound

What it means: The runtime dependency manifest is missing.

How to fix: Run agent-network setup dependencies.

Name: invalidDependencyVersion

What it means: A dependency version isn’t valid SemVer.

How to fix: Use SemVer (for example 2.1.3).

Name: projectAlreadyExists

What it means: The target project or directory already exists.

How to fix: Use a new name or directory.

Name: invalidAssetVersion

What it means: The asset version isn’t valid SemVer.

How to fix: Use SemVer (for example 0.0.0).

Name: invalidGroupId

What it means: The group-id wasn’t found.

How to fix: Use a group-id for an org that you belong to, as listed in the message.

Name: invalidProjectName

What it means: The project name has no alphanumeric character.

How to fix: Include at least one alphanumeric character.

Name: invalidAssetId

What it means: The asset id has invalid characters.

How to fix: Use only A-Z, a-z, 0-9, _, -.

Name: missingAssetIdWithInvalidProjectName

What it means: The project name has no alphanumerics and no asset id was given.

How to fix: Provide an explicit asset id.

Name: brokerAlreadyExists

What it means: A broker with this name already exists.

How to fix: Choose a different broker name.

Name: invalidBrokerTemplate

What it means: The broker scaffold template is missing.

How to fix: Reinstall the plugin. The installation can be corrupted.

Name: unsupportedAgentNetworkVersion

What it means: The command requires a V2 project.

How to fix: Use a V2 Agent Network project.

Name: invalidAgentNetworkYaml

What it means: agent-network.yaml failed to parse.

How to fix: Fix the YAML syntax error reported in the message.

Name: invalidEmptyBrokerName

What it means: The broker name has no alphanumeric character.

How to fix: Include at least one alphanumeric character.

Name: invalidBrokerName

What it means: The broker id violates the naming pattern.

How to fix: Start and end with a letter or digit. In the middle, use only letters, digits, _, ., or -.

Name: invalidBrokersSection

What it means: The brokers YAML section isn’t a mapping.

How to fix: Make brokers: a mapping of names to definitions.

Name: brokerNameTooLong

What it means: The broker id exceeds the deployment-name length limit.

How to fix: Shorten the name of the broker.

Name: policyVersionError

What it means: Looking up a policy version failed.

How to fix: Verify the policy GAV. See Exchange.

Name: policyValidationFailed

What it means: One or more policy bindings failed validation.

How to fix: Fix the validation errors listed in the nested cause.

Name: schemaNotFoundForAsset

What it means: A policy config schema file is missing.

How to fix: Verify the policy asset includes its schema.

Name: dependencyVersionNotFound

What it means: A dependency version is absent from the descriptor.

How to fix: Add the dependency version to exchange.json.

Name: v1NotSupportedForLocalRun

What it means: run-local was invoked on a V1 project.

How to fix: Only V2 projects can run locally.

Name: dockerNotInstalled

What it means: Docker isn’t installed.

How to fix: Install Docker Desktop.

Name: dockerDaemonNotRunning

What it means: The Docker daemon isn’t running.

How to fix: Start Docker Desktop and retry.

Name: dockerSignInRequired

What it means: Docker requires sign-in.

How to fix: Run docker login or sign in via Docker Desktop.

Name: dockerImagePullFailed

What it means: A required image failed to pull.

How to fix: Confirm that you’re signed in and have network access.

Name: exchangeJsonMissingMain

What it means: exchange.json has no main field.

How to fix: Set the main field to the network YAML file.

Name: flexRegistrationFailed

What it means: Flex Gateway registration generation failed.

How to fix: Read the detail in the message and retry the request.

Name: policyImplementationNotFound

What it means: No Flex implementation exists for a policy.

How to fix: Use a policy with a Flex Gateway implementation.

Name: policyImplementationResolveFailed

What it means: Resolving a policy’s Flex implementation failed.

How to fix: Read the detail and verify the policy GAV.

Name: policyFetchFailed

What it means: Fetching a policy asset failed.

How to fix: Check network and Exchange access, and then retry the request.

Name: policyAssetCorrupt

What it means: A cached policy asset is missing exchange.json.

How to fix: Clear the cache and fetch the asset again.

Name: policyMainFileMissing

What it means: A policy asset’s declared main file is absent.

How to fix: Verify the policy asset is complete.

Name: policyDependencyMissing

What it means: A policy dependency isn’t cached.

How to fix: Rerun the command to fetch dependencies.

Name: noAvailablePort

What it means: No free port in the scan range.

How to fix: Free a port or pass --port explicitly.

Name: invalidPort

What it means: The --port value is invalid.

How to fix: Use an integer between 1 and 65535.

Name: agentGraphServiceNameCollision

What it means: Two asset ids trim to the same Docker service name.

How to fix: Rename one asset to avoid the DNS-label collision.

Name: localSecretRetrievalFailed

What it means: A stored secret couldn’t be retrieved.

How to fix: Rerun the command without a cached value and reenter the secret.

Name: unknownLlmPlatformForApiKey

What it means: An LLM platform isn’t recognized for API-key selection.

How to fix: Use a supported platform (listed in the message).

Name: undeclaredVariables

What it means: A ${…​} placeholder is used but not declared.

How to fix: Declare each variable under metadata.variables in exchange.json.

Name: dockerAgentGraphImageMissing

What it means: The Agent Graph image isn’t published yet.

How to fix: Use --build-only, which doesn’t require the image. Local deploy is unavailable without the image.

Name: localEnvironmentNotRendered

What it means: A local-deploy command ran before run-local.

How to fix: Run agent-network project run-local first.

Name: secretEnvVarNameCollision

What it means: Two secret variables normalize to the same environment variable name.

How to fix: Rename one to avoid the collision.

Name: secretRouteSegment

What it means: A secret variable is used in a route path segment.

How to fix: Use a non-secret variable for the path.

Name: secretUpstreamAddress

What it means: A secret variable is used in an upstream URL.

How to fix: Use a non-secret variable, or supply the credential via a policy.

Name: flexCrdNameCollision

What it means: Two Flex Gateway CRD (Custom Resource Definition) ids collapse to the same filename.

How to fix: Rename one of the colliding ids.

Name: connectionPolicyResolverRequired

What it means: Internal: local render lacks a connection policy resolver.

How to fix: Rebuild and rerun. If the error persists, then report it with the requestId.

Name: apiInstancePolicyResolverRequired

What it means: Internal: local render lacks an API-instance policy resolver.

How to fix: Rebuild and rerun. If the error persists, then report it with the requestId.

Name: localExchangeDestinationUnsafe

What it means: A local Exchange asset has an empty or unsafe destination.

How to fix: Rename the asset or dependency to a safe id.

Name: localExchangeDestinationCollision

What it means: Two local Exchange assets map to the same destination.

How to fix: Rename an asset or use a distinct dependency.

Name: malformedBuildOutputAssetKeyMismatch

What it means: Internal: build-output asset map key mismatch.

How to fix: Rebuild the project. If the error persists, then report it with the requestId.

Name: malformedBuildOutputMissingComponentVersion

What it means: Internal: an owned asset has no component version.

How to fix: Rebuild the project. If the error persists, then report it with the requestId.

Name: malformedBuildOutputDuplicateAssetIdentity

What it means: Internal: duplicate owned-asset identity.

How to fix: Rebuild the project. If the error persists, then report it with the requestId.

Name: malformedBuildOutputEmptyDestination

What it means: Internal: an owned asset has an empty destination.

How to fix: Rename the asset and rebuild.

Name: malformedBuildOutputDestinationCollision

What it means: Internal: two owned assets map to the same destination.

How to fix: Rename an asset and rebuild.

Name: localRenderAggregateFailure

What it means: One or more local-render tasks failed. This error consolidates the failures.

How to fix: Read the logs for each sub-failure.

Name: localRunUnsupportedProjectType

What it means: run-local was invoked on a project that isn’t an Agent Network.

How to fix: Run local deployment from an Agent Network V2 project. A V1 project reports code 8500 instead.

Name: genericError

What it means: An uncategorized failure. The message carries the specific reason.

How to fix: Read the errorMessage and nested cause. See Dependent Services: Status Codes and Common Issues for an underlying service error.

Name: credentialsValidationsError

What it means: Credential validation failed.

How to fix: Reauthenticate and verify your credentials. See Access Management.

Name: gatewayFlagsMutuallyExclusive

What it means: --gateway was combined with --ingress-gw/--egress-gw.

How to fix: Use --gateway alone, or --ingress-gw [--egress-gw].

Name: egressGwRequiresIngress

What it means: --egress-gw was passed without --ingress-gw.

How to fix: Pass both, or use --gateway.

Name: gatewayFlagRequired

What it means: No gateway flag was supplied.

How to fix: Pass --gateway or --ingress-gw [--egress-gw].

Name: separateGatewayModeNotSupportedInSharedSpace

What it means: Separate-gateway mode was used with a Shared Space.

How to fix: Use --gateway, or pass a Private Space to --target-space.

Name: singleGatewayTargetSpaceMismatch

What it means: --target-space conflicts with the gateway’s target space.

How to fix: Omit --target-space, or make it match the gateway.

Name: forceFlagRequiredWithJson

What it means: --json was used without --force.

How to fix: Add --force to skip interactive prompts.

Status / symptom: 409, asset already exists

Likely cause: An asset with this id exists with a different type or owner.

Fix: See codes 2005 and 2006. Use a new id or version, or reconcile ownership.

Status / symptom: 403 Forbidden (surfaces as code 2010)

Likely cause: A known Exchange platform issue.

Fix: Retry later. If the error persists, then open a support case with your requestId. This known platform issue can’t be resolved locally.

Status / symptom: 404

Likely cause: The asset is already gone.

Fix: No action. The CLI treats the response as a success.

Status / symptom: 5xx or 429

Likely cause: Transient platform load.

Fix: The CLI retries automatically. If the error persists, then retry later.

Status / symptom: Missing zip classifier (run-local only)

Likely cause: Some policy versions (for example user-context-propagation-policy-flex@1.0.0) were published without a zip classifier.

Fix: This policy version is missing a required file in Exchange. Open a support case to request that MuleSoft republish it with a zip classifier. Production deploy is unaffected.

Status or symptom: 409 Conflict (code 3001)

Likely cause: A stale or orphaned instance from a prior partial deploy, or a name collision.

Fix: Check API Manager for an existing instance with that name. Delete or reuse the instance, and then redeploy.

Status or symptom: non-2xx (code 3010)

Likely cause: The target instance changed or was removed.

Fix: Read the cause and verify that the instance still exists.

Status or symptom: failure (code 3047)

Likely cause: A policy GAV resolution or org entitlement problem.

Fix: Verify the policy GAV and confirm that your org is entitled to the policy.

Status or symptom: empty or invalid (code 3031)

Likely cause: A transient error or a bad policy GAV.

Fix: Retry the request. If the error persists, then verify the policy GAV.

Status or symptom: 404

Likely cause: The instance was already removed.

Fix: No action. The CLI treats the response as a success.

Status or symptom: "Deployment status request returned status N"

Likely cause: A non-retryable HTTP error, or retries exhausted.

Fix: Read the status and check the deployment in Runtime Manager.

Status or symptom: request timeout (code 3017)

Likely cause: The request exceeded --request-timeout.

Fix: Retry the request and increase --request-timeout.

Status or symptom: command timeout (code 3018)

Likely cause: The org can lack sufficient resources, or the deploy can be slow.

Fix: Review org resource allocation and increase --process-timeout. Check steps for progress.

Status or symptom: failure (codes 3008 and 3028)

Likely cause: Underlying AMC error.

Fix: Read the logs and nested cause.

Status or symptom: 404

Likely cause: Already removed.

Fix: No action. The CLI treats the response as a success.

Status or symptom: name collision (code 4013)

Likely cause: The environment already contains a gateway with this name.

Fix: Choose a different name.

Status or symptom: insufficient resources (code 4014)

Likely cause: The org’s gateway quota is exhausted.

Fix: Delete an unused gateway or increase org limits.

Status or symptom: no domains (codes 4001 and 4015)

Likely cause: No private network in the target space.

Fix: Create a private network for the target space first.

Status or symptom: non-success status (codes 4003 and 4005)

Likely cause: Downstream gateway or API Manager error.

Fix: Read the status and response in the message, and then retry the request.

Status or symptom: non-2xx (codes 4008–4010)

Likely cause: A transient or access issue.

Fix: Retry the request and verify org and environment access.

Status or symptom: non-2xx (code 5001)

Likely cause: A transient error or a missing org entitlement.

Fix: Retry the request and verify that the org is entitled to Agent Fabric.

Status or symptom: denied (code 5002)

Likely cause: You lack access to the org that owns the groupId.

Fix: Switch orgs or request access.

Status or symptom: mismatch (code 5003)

Likely cause: The groupId doesn’t match your selected org or business group.

Fix: Switch to the org that owns the assets.

Status or symptom: failure (code 10001)

Likely cause: Expired or invalid credentials.

Fix: Reauthenticate.

Status or code: 403 → code 2010

Classification: Known Exchange platform issue. Retry later. If the error persists, then open a support case with your requestId.

Status or code: run-local fetch failure

Classification: Missing file in Exchange. Open a support case to request a republish. Production deploy is unaffected.

Status or code: code 8519

Classification: External blocker. Use --build-only because the image isn’t published.

Status or code: 409 → code 3001

Classification: Environment state. The cause is usually an orphaned instance. Check API Manager and delete or reuse the instance.

Status or code: 429, 5xx

Classification: Transient platform load. The CLI already retries the request.

Status or code: codes 4003–4010

Classification: Downstream relay. The CLI passes through the status that the gateway or API Manager service returns.