Troubleshooting

This page lists the problems people run into in Alara Code, grouped by where you see them. For each one you get the text you see, what causes it, and how to fix it. Most messages already name the fix; this page explains the ones that do not.

When a step fails, its turn in SDLC Studio shows a short summary ("The agent declined this step", "Your session expired", ...) with a hint underneath. Click Details to see the exact message the bridge recorded; that message, or the code at its start, is what you look up here. The same text is kept in the project's Run History tab.

Where errors appear

Drawing diagram…

• Toasts appear when the bridge refuses a request before any work starts: no permission, a locked step, another run in progress, an expired session, an unreadable file.
• A failed turn appears when a step started but did not finish. Its summary is written for people; the text under Details is the bridge's own.
• A failed chat reply appears in the conversation in place of the agent's answer.

The agent and its skills

"The agent declined this step"

What you see. A failed turn titled "The agent declined this step", with a reason such as the skill file not being available, and the hint "Check that the agent has every skill file attached in Alara, then run the step again." Under Details the message looks like AGENT_INVALID_REPLY: sdlc-scope-analyst: the agent declined — ....

Cause. Every step asks the project agent to apply one named skill file. When the agent cannot see that file, or the input lacks something the file needs, it is instructed to refuse with a one-sentence reason rather than improvise. The most common cause is a skill file that was never added to the agent in Alara, or was removed.

Fix.

1. Open Settings in the project, go to the Agent section and click Check agent.
2. If it reports "N skill files are missing from this agent", add the listed files to the agent as reference files in Alara, then click Check agent again until it says "The agent sees every skill file — it is ready to run steps."
3. Run the step again.

See Set up the project agent for the full list of skill files.

Check agent reports missing skill files

What you see. In Project Settings, under Agent: "N skill files are missing from this agent." followed by "Add these reference files to the agent in Alara (Settings › Organization agents has the skill pack), then check again:" and the file names.

Cause. Check agent asks the bound agent which skill files it can see, and compares the answer with the files the pipeline needs.

Fix. Add each listed file to the agent in Alara. The skill pack is available under Settings › Organization agents in Alara Code. Then check again.

The chat says the agent does not have its chat skill

What you see. A chat reply reading "The project agent does not have its chat skill. In Alara OS, add sdlc-project-assistant.md to the agent's knowledge base (link it with the other sdlc-*.md files) and save, then send the message again."

Cause. The project chat uses its own skill file, sdlc-project-assistant.md. Without it the agent refuses to answer.

Fix. Add the file to the agent in Alara, save, and send the message again.

AGENT_REPLY_TIMEOUT — "The agent took too long to answer"

What you see. A failed turn titled "The agent took too long to answer", hint "Check the agent's model limits in Alara, then run the step again." Details: AGENT_REPLY_TIMEOUT: The agent did not answer in time — ... Check the agent in Alara (skills, model limits) and re-run.

Cause. Each call to the agent has a deadline (ten minutes by default). No reply arrived before it. A slow or overloaded model, a model with a low output limit that stalls on a long document, or a reply that was lost on Alara's side can all cause it.

Fix. Check the agent's model and its limits in Alara, then run the step again. In the chat the same cause reads "The agent did not answer in time. Send the message again."

AGENT_CALL_FAILED — "The agent's model failed"

What you see. A failed turn titled "The agent's model failed", hint "Check the agent's model in Alara, then run the step again." Details start with AGENT_CALL_FAILED: and end "Check the agent's model in Alara and re-run."

Cause. Alara reported that the agent's run failed — typically the model provider behind the agent returned an error.

Fix. Check the agent's model configuration in Alara, then run the step again.

AGENT_INVALID_REPLY — "The agent's reply was not in the expected format"

What you see. A failed turn titled "The agent's reply was not in the expected format", hint "Run the step again; if it keeps failing, check the agent's skill files in Alara." Details start with AGENT_INVALID_REPLY: and say, for example, "the agent's reply was not valid JSON" or "the agent returned an empty reply". The toast version is titled "The agent did not return the contract".

Cause. Each skill expects a reply in a fixed JSON shape (the contract). The agent answered with something else: prose, a truncated reply, or nothing at all. When the reply is the agent refusing, you see "The agent declined this step" instead (above).

Fix. Run the step again. If it keeps failing, check that the agent's reference files are the current skill files and that its system prompt is the one Alara Code provides.

AGENT_NOT_AVAILABLE — "The project's agent is not available"

What you see. "Agent not available" (toast) or "The project's agent is not available" (failed turn), with the hint "Choose another agent in Project Settings › Agent." The message is one of:

• "The agent bound to this project is no longer shared with your organization in Alara. Bind another one in Project Settings › Agent."
• "Alara does not know that agent (...)."
• "That agent is not a reasoning (brain) agent and cannot run Alara Code skills."

Cause. Before every run the bridge checks the bound agent against the agents Alara currently shares with your organization. The agent was unshared, deleted, or is not a reasoning agent.

Fix. Open Settings › Agent in the project, click Change agent, pick one of the organization's agents and click Bind agent. If the agent you want is missing from the list, ask your Alara administrator to share it with Alara Code for your organization.

NO_AGENT_BOUND — "No Alara agent bound"

What you see. The composer shows "No Alara agent bound" and "Bind one of the organization's agents in Project Settings › Agent before running a step.", with an Open Project Settings link. A refused request shows the toast "No agent bound".

Fix. Bind an agent in Settings › Agent. No step can run without one.

Changing or removing the agent is refused

What you see. "A step is running on this project. Wait for it to finish, then try again." The agent buttons also show "Unavailable while a step is running."

Fix. Wait for the running step to finish, or stop it, then change the agent.

Alara and your session

SESSION_EXPIRED — "Your session expired"

What you see. A failed turn titled "Your session expired" with "Sign in again, then run the step again", or the message "Your Alara session has expired — sign in again." In the chat: "Your session expired while the agent was answering. Sign in again, then resend."

Cause. Steps run on the agent as you, using your sign-in. Your sign-in ran out during the run, or Alara rejected it as expired.

Fix. Sign in again and run the step (or resend the message). When any request finds your session gone, Alara Code signs you out and takes you to the sign-in page.

SESSION_EXPIRES_SOON — "Sign in again first"

What you see. A toast titled "Sign in again first": "Your session is about to expire — sign in again and re-run the step."

Cause. A step can take up to the run budget (25 minutes by default), and it needs your sign-in for the whole time. If your sign-in would expire before that, the bridge refuses to start rather than fail the step halfway through.

Fix. Sign out, sign in again, and run the step.

AGENT_REQUIRES_USER_SESSION — "Browser session required"

What you see. "Alara agents run as the signed-in person; this session carries no Alara identity (sign in through the browser)." When binding an agent: "Binding an agent needs your browser session — sign in through the browser."

Cause. Steps, chat and agent binding run as you in Alara, which needs a browser sign-in. A session without an Alara identity, such as the development-only local sign-in, cannot start them.

Fix. Start the step from the Alara Code web app while signed in.

ALARA_DENIED — "Alara refused the request"

What you see. "Alara refused the request (...)." with Alara's own reason in the brackets, and the hint "Check that you can use this agent in Alara."

Cause. Alara answered, but refused — for example because you are not permitted to use this agent, or a limit on Alara's side was reached. The reason in brackets is Alara's.

Fix. Act on Alara's reason. If it concerns access, ask your Alara administrator.

ALARA_UNAVAILABLE — "Alara is not reachable"

What you see. "Alara is not reachable right now — try again shortly." or "Alara could not resolve the organization's agents — try again shortly."

Cause. The bridge could not reach Alara, or Alara could not look up your organization's agents.

Fix. Wait a moment and try again. If it persists, tell your administrator; nothing in the project needs changing.

ALARA_NOT_CONFIGURED — "Alara agents are not set up here"

What you see. "Alara agents are not configured on this deployment (ALARA_API_BASE_URL / BRAIN_STREAM_BASE_URL)."

Cause. The deployment is missing the settings that connect it to Alara.

Fix. An administrator sets the named variables. See Deployment and configuration.

ALARA_ERROR — "Alara answered unexpectedly"

What you see. "Alara answered unexpectedly (...)."

Fix. Run the step again. If it repeats, report the text under Details to your administrator.

BRAIN_PIPELINE_REQUIRED — "Alara agents are switched off"

What you see. A toast titled "Alara agents are switched off": "SDLC commands run on the project's Alara agent. Set BRAIN_PIPELINE=true on the bridge to run them."

Cause. Steps run only on Alara agents, and this deployment has that path turned off.

Fix. An administrator enables it on the bridge. There is no other way to run steps.

Running steps

A step is locked

What you see. In the composer, a step shows with a lock and a dashed border. Hovering it says "Approve /scope to unlock this", "Run /sds first", or "An earlier phase has to finish first". If a request reaches the bridge anyway, the toast is titled "Locked": "Command /srs is locked. Complete /scope first."

Cause. Steps run in order, with a human approval between them. Scope waits for an approved RFP; SRS for an approved Scope; SDS for an approved SRS; STS for an approved SDS. Tasks and Compliance open once the STS exists, Traceability once the SDS exists, and the Proposal needs Scope, SRS and SDS plus an approved STS.

Fix. Do what the tooltip says: approve the named step, or run it. See How the pipeline works.

LOCK_CONFLICT — "Another command is running"

What you see. A toast titled "Another command is running" with one of:

• "Another command is already running for this project."
• "A command is running for this project. Wait for it to finish before approving."
• "A command is running for this project. Wait for it to finish before uploading the RFP."
• "Cannot delete project while a command is running"

Cause. A project runs one step at a time — including one started by someone else. Approving, uploading an RFP and deleting the project also wait for it.

Fix. Wait for the running step to finish (it shows in SDLC Studio, and in Run History as running), or stop it with Stop. You can keep chatting with the agent while a step runs.

ORG_CONCURRENCY_LIMIT — "Organization limit reached"

What you see. "Your organization already has N of M agents running. Wait for one to finish, then try again."

Cause. Your organization has a cap on how many steps can run at the same time across all its projects, and it is reached.

Fix. Wait for another run to finish, then start the step again.

"Accepted with N unresolved checks"

What you see. The document is ready for review, and a note above Approve lists checks it still fails — for example a missing section, an id that is never cited, or too few diagrams.

Cause. The bridge checks every document the agent writes: the required section headings, every id the step owns, each ```mermaid block closed and starting with a diagram type, the minimum number of diagrams, and a size limit. A failed check goes back to the agent with its own draft and each problem located. When the attempts run out with only document problems left, the draft is kept for you rather than thrown away.

Fix. Read the listed checks against the document. Approve it if the gaps do not matter, or use Request changes and name them — the agent revises the draft with your notes.

"The agent's reply still fails N check(s) the next step depends on"

What you see. A failed turn whose reason lists, under "Still failing:", each check with where it is, what was expected and what was found — for example a requirement with a category outside the allowed list, or a design component whose units do not cover its requirements.

Cause. These checks guard the data later steps read (requirements, test cases, the design's components and units, compliance findings), or the document was empty. After every correction attempt the reply still broke one of them, so the step stopped instead of saving data that would break the next step. The agent's last reply is kept in the project's .sdlc/tmp folder.

Fix. Run the step again; if the same check keeps failing, add a note naming it, or check the agent's model and persona in Alara. See Document checks and versioning.

"Command /X finished but did not produce ..."

Precondition messages

Some failures name a missing input, for example "artifacts.srs missing — run /srs first.", "requirements[] is empty — run /srs first.", "designComponents[] is empty — run /sds first." or "No implementation units on: DC-003 — re-run /sds (it now emits implementationUnits)." Run the step the message names, then try again.

"The step failed" with no reason

What you see. "The step failed" and "Run it again, or open Run History for the full record." The live output may have said "Command failed. Check server logs."

Cause. An unexpected error on the bridge. The full message is kept in Run History.

Fix. Run the step again. If it repeats, send the Run History message to your administrator.

Runs marked as errors after an interruption

In each case, run the step again.

Stop fails

"Run is not active" means the run had already finished when you clicked Stop. Refresh the page to see its outcome.

Connecting Alara Plan

In Settings › Alara Plan, paste two things from Alara Plan's Settings › Service keys › New key screen: the service key and the organization id shown beside it, each with its own Copy button. Alara Plan is its own workspace, so its organization id is not this organization's. Plan checks both, and that you are a member there, before anything is saved.

"This key belongs to another Alara Plan organization"

The organization id doesn't match the organization the key was created in. Copy the id shown beside that key in Plan, not this organization's id.

"That Alara Plan organization is already connected to another Alara Code organization"

Each Alara Plan organization serves one Alara Code organization. Ask whoever connected it to disconnect it in their Settings › Alara Plan (possible once none of their projects is linked), or use a key from a different Plan organization.

"This organization's projects are linked to Alara Plan organization …"

While any project is linked to Alara Plan, the Plan organization can't change: those projects only exist there. Save a key created in that same Plan organization. Disconnecting keeps the pairing for the same reason, so a new key from it resumes syncing.

"Your account isn't in this organization in Plan yet"

Plan acts as you, and only accepts people its organization knows: on a team, a department head, or a participant. Ask a Plan admin to add you to a team, then try again.

Review and approval

A step shows "re-run, upstream changed"

What you see. An approved step's button in the composer reads /srs re-run, upstream changed.

Cause. A step it depends on was run again after it was produced, so it was built on an older version of its inputs. Its approval still stands; the label tells you it may be out of date.

Fix. Re-run the step if the upstream change matters to it, then review and approve the new version. Re-running a step replaces its draft and asks for approval again. See Review, approve, request changes.

Project chat

Uploading an RFP

Permissions

"Permission required" / "Needs Projects › Run › create"

What you see. A disabled button whose tooltip reads "Needs <module> › <action>", or a toast titled "Permission required": "Your role does not include <module> › <action>. Ask an organization administrator to add it to your role in PolyX."

Cause. Where your deployment enforces module permissions, each action needs a grant in your organization role: Projects › Run for running, approving, requesting changes, uploading an RFP and chatting; Projects › Abort for Stop; Projects › Binding for the agent; Projects › update for moving board tickets; Integrations for the repository. Creating a project gives you no extra rights on it.

Fix. Ask an organization administrator to add the named grant to your role in PolyX. Changes can take a minute to reach Alara Code. See Members and permissions.

"Project not found"

What you see. "Project not found" and "The project may have been deleted or you do not have access."

Cause. The project was deleted, or you cannot see it: it is in your organization but not shared with a team you are on (the bridge answers 403), or it belongs to another organization (404). The page reads the same in every case.

Fix. Check that you are signed in to the right organization, and ask the project's creator or an organization administrator to give your team access.

"Not available"

A toast titled "Not available" ("This route is not mapped to a module.") means the action has no permission rule on this deployment. Report it to your administrator.

Documents

A document shows raw Markdown

Cause. The reader's view switch is on Markdown, which shows the source the document is written in.

Fix. Click Preview in the switch at the top of the document (next to its status badge). The choice resets to Preview when you open another document.

A diagram is not drawn

What you see. "Drawing diagram…" that stays, or "This diagram could not be drawn: ..." followed by the diagram's source.

Cause. Diagrams are drawn in your browser from the Mermaid text in the document. The bridge checks that each diagram block is closed and starts with a known diagram type, but it cannot check every detail of the syntax, so an occasional diagram fails to draw. The rest of the document is unaffected.

Fix. The source shown under the error still carries the content. To get a corrected diagram, use Request changes while the document is under review and name the diagram, or re-run the step. If diagrams never draw, reload the page: the drawing library loads the first time a diagram appears.

The document card has not appeared yet

Cause. A turn offers its document card only once the run has written the document and has not failed or been stopped. While the step is working you follow it in the live panel; a failed or stopped run never shows a card, because the document registered for that step is still the previous version.

Fix. Wait for the step to reach "Awaiting your review" (or "Approved" for steps without review). If the run failed, fix the cause and run it again. Older documents are always available in the Artifacts tab.

"Document not available" and other reader messages

See Read and export documents.

Board and repository

For "No tickets yet", "Publish failed", "Sync failed" and the Alara Plan banners, see The delivery board. Tickets are moved in Alara Plan, not on the board. For repository connection and push errors, see Repository integration.