MCS Engine Error Reference

When the MCS Engine cannot continue, it prints an error to the terminal and records it in the session's engine.log. The web interface shows the same text. Every error has the form:

E#### - <what went wrong>
        <an optional indented line telling you what to do>

The E#### code names the category of the problem. The message says what happened. Many errors add an indented hint line with the fix, and where a path, name, or number is involved it is shown in the message.

This guide has three parts: a category map so you know roughly where a problem lies, step-by-step fixes for the errors you are most likely to hit, and a complete catalog of every code the engine can emit.

If you contact support about an error, copy the entire line (code and message). That is enough for us to locate the exact cause.

Error categories at a glance

Range What it covers First thing to check
E1xxx Loading and parsing the engine config (mcs.conf) and the session config (.conf) The config paths you passed and the file contents
E2xxx Session and participant validation Your participant list in the session config
E4xxx Session setup and writing output files Disk space and write permission on the session directory
E5xxx A single request to a model provider and its reply The participant's endpoint, API key, and model name
E6xxx Run-configuration rules (mode, transport, tier) Whether your tier allows the mode/transport you chose
E7xxx The turn-by-turn deliberation exchange Provider reachability and the per-turn messages in the log
E8xxx Licensing, signature checks, license server, web access Your license file and network connectivity
E9xxx Internal engine bookkeeping and command-line arguments Usually internal; check your command-line flags

Common errors and how to fix them

The errors below are the ones you are most likely to encounter, with the cause and the fix. The codes in parentheses are where you will see them.

The engine cannot find its configuration (E1000)

You will see one of: Cannot find mcs.conf in any default location, Cannot open config file, or CLI mode requires -s <path>.

Cause: the engine could not locate the engine config (mcs.conf) or the session config you intended to run.

What to do: - Pass the engine config explicitly with -c <path>, or set MCS_CONFIG. - Pass the session config with -s <path>. - Or place mcs.conf in one of the default search locations listed in the error's hint lines.

The session agenda is missing or empty (E1001, E1002, E1003)

Messages: session config has no agenda, session config missing AGENDA_END tag, or AGENDA block is empty.

Cause: the session config's agenda block is absent, unterminated, or has no content.

What to do: make sure your session config contains an agenda delimited by AGENDA_START and AGENDA_END, with the agenda text between them.

Too few participants, or a human participant (E2000, E2300)

Messages: Need at least 2 participants or Human participant ... not supported in V1.

Cause: a deliberation needs at least two participants, and in this version all participants must be AI models.

What to do: define at least two participants in the session config, and remove any human participant entries.

A file type your tier cannot use (E4015)

Message: File '...' rejected: format '...' not allowed on <tier> tier. <tier> or higher required. Session start aborted.

Cause: you supplied an input file (or requested an output format) that your license tier does not permit.

What to do: use a format your tier allows, or upgrade to the tier named in the message. See the user guide's tier and format matrix for the full list.

No license, or an invalid or expired license (E8000, E8001, E8002, E8003, E8004, E8005)

Messages range from Cannot find license.key in any default location and License file not found to License signature invalid, License expired N days ago, Unknown tier, and License schema version ... not supported.

Cause: the engine could not find a license, or the license it found is malformed, tampered with, expired, or made for a different build.

What to do: - Provide the license with --license-key <path>, set MCS_LICENSE_KEY, or place license.key in one of the default locations in the hint lines. - If the license is expired or rejected, obtain a current one from osinix.com. - A schema-version mismatch means the engine and license are from different generations; use a license issued for this build.

Too many participants for your license (E8020)

Message: License allows max N participants (<tier> tier). Requested: M.

Cause: your session has more participants than your tier permits.

What to do: reduce the participant count, or upgrade to a tier with a higher limit.

The license server is unreachable (E8205, E8206, E8207)

Messages: license server unreachable, license server returned HTTP ..., or malformed license server reply.

Cause: the engine performs a periodic license check and could not complete it.

What to do: this is usually a transient network or DNS problem, and the engine tolerates short outages through an offline grace period, so a single occurrence is rarely fatal. Check your internet connection and DNS. If it persists past the grace period and the engine stops, contact support with the full message.

Your tier does not allow the chosen mode or transport (E6020, E6021)

Messages: Directed mode requires Pro tier or higher or Parallel transport requires Pro tier or higher.

Cause: directed mode and parallel transport are Pro-and-above features.

What to do: use roundtable mode and sequential transport (set transport = 0 or omit it), or upgrade your tier.

A participant has no endpoint (E5030)

Message: Missing/empty endpoint for participant ....

Cause: a participant in the session config has no model endpoint set.

What to do: give every participant a valid endpoint in the session config.

A model provider returned an error (E5011, E5021)

Messages: Anthropic API error: ... or OpenAI API error: ... (the provider's own text follows).

Cause: the model provider rejected the request. Common reasons are an invalid API key, an unknown model name, a rate limit, or an account with no credit.

What to do: check the participant's API key, model name, and endpoint, and confirm the provider account is active and funded. The provider's message after the colon usually says which.

The session reached its turn limit (E4000)

Message: Session turn limit reached: N.

Cause: the deliberation ran to the configured maximum number of turns. This is informational, not a failure.

What to do: if you need a longer session, raise max_turns (within your tier's limits) and run again.

The web interface will not start (E8300, E8301, E8302, E8303)

Messages: Cannot create socket, No free port in range, Cannot listen, or Accept failed.

Cause: the web interface could not open or bind a network port. The most common case is that every port in its scan range (8700-8799) is already in use.

What to do: close other programs that may be holding those ports and try again. If it persists, check that local security software is not blocking the engine from opening a socket.

Appendix: complete error reference

Every error code the engine can emit, with what it means and what to do. Generated from the source and tools/error_descriptions.json by tools/gen_error_reference.py; regenerate after changing any error message or description. The Message column shows what the engine prints (text like %s or %d is filled in at run time); find your error by matching that text. Entries marked (internal) are diagnostics you are unlikely to see; if one appears, copy the full line and contact support.

Total: 112 codes across 8 ranges (172 raw emissions).

E1xxx -- Configuration (engine and session config loading/parsing)

Code Message What it means What to do
E1000 CLI mode requires -s to specify session.conf.
-b requires a browser name
-c requires a config file path
-s requires a session config file path
--license-key requires a file path
mcs_cfg_parse_buffer: out of memory
Cannot stat session config file: %s: %s
Session config file is empty: %s
Cannot open session config file: %s: %s
Out of memory reading config
Short read on config file: %s
Cannot open config file: %s
Cannot find mcs.conf in any default location.
Cannot open config file: %s: %s
Cannot stat config file: %s
Cannot allocate config buffer
Cannot read config file: %s
session config: null path or output
The engine could not read a configuration file (its own mcs.conf or the session .conf), or a required command-line flag was given without its argument. Check the paths you passed (-c for the engine config, -s for the session config), confirm the files exist and are readable, and that each flag has its argument. The hint line names the default search locations.
E1001 session config has no agenda The session config has no agenda block. Add an agenda delimited by AGENDA_START and AGENDA_END, with the agenda text between them.
E1002 session config missing AGENDA_END tag The session config opened an agenda block but never closed it. Add the AGENDA_END tag after your agenda text.
E1003 AGENDA block is empty The agenda block is present but contains no text. Put the agenda content between AGENDA_START and AGENDA_END.

E2xxx -- Session and participant validation

Code Message What it means What to do
E2000 Need at least 2 participants, found %d A deliberation needs at least two participants, and fewer were defined. Define at least two participants in the session config.
E2300 Human participant '%s' not supported in V1
[PAR] Human participant '%s' reached transport layer but is not supported in V1.
Human participant '%s' reached transport layer but is not supported in V1.
[DIRECTED] Human participant '%s' reached transport layer but is not supported in V1.
A human participant was configured or reached the engine. This version supports AI participants only. Remove human participant entries; all participants must be AI models in V1.

E4xxx -- Session setup and file I/O

Code Message What it means What to do
E4000 Failed to create test session
Failed to build payload for %s
Cannot allocate payload buffer
Cannot allocate payload struct
Cannot allocate payload text
Cannot create directory: %s (errno=%d)
Cannot create session: null config
Cannot allocate session
Session turn limit reached: %d
Cannot add message to ended session
Cannot allocate message
Cannot allocate response text
Cannot allocate summary text
Cannot allocate context request
The engine could not set up or advance the session, or a session limit such as the turn limit was reached. Read the specific message. For a turn limit, raise max_turns within your tier's limits. For setup failures, check the session directory, permissions, and free disk space.
E4015 File '%s' rejected: format '%s' not allowed on %s tier. %s or higher required. Session start aborted. An input file's format is not permitted on your license tier, so the session was not started. Use a format your tier allows, or upgrade to the tier named in the message. The user guide lists the tier and format matrix.
E4100 status.json.tmp path too long: %s
status.json path too long: %s
The path the engine built for the status file was too long for its buffer. Use a shorter session directory path.
E4101 Cannot open %s for writing: %s The engine could not open a file for writing. Check write permission and free space on the session directory.
E4102 fclose failed on %s: %s Closing a file after writing failed, which can mean the data was not fully flushed to disk. Check free disk space and the underlying storage.
E4103 rename %s -> %s failed: %s Renaming a temporary file to its final name failed. Check permissions, and that the temporary and final paths are on the same filesystem.
E4110 save_returned_binary: invalid arguments (internal) An internal call that saves model-produced binary content received invalid arguments. Diagnostic. If you see it, copy the full line and contact support.
E4111 cannot resolve media path for %s
cannot open %s for write
The engine could not resolve the output path for a file a model produced. Check the session's media directory and its permissions.
E4112 base64 decode failed for %s Decoding a base64 file produced by a model failed. The provider returned malformed data. Retry; if it persists, contact support with the log.
E4113 could not register %s as FILE_REF The engine could not register a produced file as a file reference for later turns. Check the session media directory and permissions; if it persists, contact support.
E4200 No moderator defined in session.conf
Moderator '%s' not found in participant list
No moderator is defined in the session config. Add a moderator entry to the session config.

E5xxx -- Provider request/response (single HTTP call)

Code Message What it means What to do
E5000 curl_global_init failed: %s (internal) The HTTP library failed to initialize. Diagnostic, usually an environment or TLS setup problem. Contact support if it persists.
E5002 Out of memory in HTTP response buffer The engine ran out of memory while buffering a provider's HTTP response. The reply was very large or memory is exhausted. Free memory and retry.
E5010 Anthropic response missing 'content' field The Anthropic provider's reply was missing its expected content field. Usually a provider-side issue or an unexpected model. Verify the model name and retry.
E5011 Anthropic API error: %s The Anthropic provider returned an error; its own text follows the colon. Check the participant's API key, model name, rate limits, and account credit. The provider's text usually says which.
E5012 Anthropic response has no text content block
Failed to find text field after type
The Anthropic reply contained no text content block. Verify the model name and retry; the model may have returned only non-text content.
E5013 text field is not a string A text field in the Anthropic reply was not the expected string type. Provider returned an unexpected shape. Verify the model and retry.
E5014 Extracted empty text from Anthropic response The Anthropic reply parsed but yielded empty text. The model returned nothing usable. Retry, or adjust the prompt or model.
E5020 OpenAI response missing 'choices' field The OpenAI-style reply was missing its choices field. Verify the model name and that the endpoint is OpenAI-compatible, then retry.
E5021 OpenAI API error: %s The OpenAI-style provider returned an error; its own text follows the colon. Check the participant's API key, model name, rate limits, and account credit.
E5022 OpenAI response missing 'message' field The OpenAI-style reply was missing its message field. Verify the model and endpoint, then retry.
E5024 Model returned neither text nor binary content The model returned neither text nor binary content. The model produced nothing usable. Retry, or adjust the prompt or model.
E5030 Missing/empty endpoint for participant (request setup)
Missing/empty endpoint for participant (URL build)
Missing/empty endpoint for participant (payload build)
A participant has no model endpoint configured. Set a valid endpoint for every participant in the session config.
E5031 Failed to build request body The engine could not build the request body for a provider call. Check the participant's configuration; if it persists, contact support.
E5032 curl_easy_init failed (internal) The network library could not initialize a request handle. Diagnostic, usually an environment problem. Contact support if it persists.
E5033 curl failed (attempt %d/%d): %s A network call to the provider failed mid-flight; the attempt number is shown. Usually transient. The engine retries automatically. Check connectivity and the endpoint if it persists.
E5034 HTTP %ld from %s (attempt %d/%d)
HTTP error %ld from %s
The provider returned an HTTP error status; the code and attempt are shown. Check the endpoint, API key, and rate limits. 4xx usually means a bad key or request; 5xx is provider-side.
E5045 Gemini response missing 'parts' field The Gemini reply was missing its parts field. Verify the model name and retry.
E5046 Gemini error: %s The Gemini provider returned an error; its text follows. Check the participant's API key, model name, and account status.
E5048 Gemini text part not a string A Gemini text part was not the expected string type. Provider returned an unexpected shape. Verify the model and retry.
E5100 Cannot write turn file: %s
Cannot write summary file: %s
Cannot write metadata: %s
The engine could not write a turn's output file. Check free disk space and write permission on the session directory.

E6xxx -- Run-configuration gates (mode, transport, tier)

Code Message What it means What to do
E6010 Failed to create session The engine could not create the session. Check the session directory, permissions, and your configuration.
E6011 Failed to initialize HTTP subsystem (internal) The HTTP subsystem failed to initialize at session start. Diagnostic, usually an environment or TLS issue. Contact support if it persists.
E6012 Round %d failed — ending session A deliberation round failed, so the session was ended. Read the preceding messages and the session's engine.log for the underlying cause, which is usually a provider failure.
E6013 Pre-Session Briefing: Failed to build payload The pre-session briefing step could not build its request. Check the moderator's configuration; if it persists, contact support.
E6014 Pre-Session Briefing: No response from moderator The pre-session briefing step got no response from the moderator. Check the moderator's endpoint, API key, and connectivity.
E6020 Directed mode requires Pro tier or higher (current: %s). Use roundtable mode instead. Directed mode is a Pro-and-above feature and your tier is lower. Use roundtable mode, or upgrade your tier.
E6021 Parallel transport requires Pro tier or higher (current: %s). Use 'transport = 0' or omit the field for sequential. Parallel transport is a Pro-and-above feature and your tier is lower. Use sequential transport (set transport = 0 or omit it), or upgrade your tier.
E6022 Directed mode is incompatible with parallel Directed mode cannot run with parallel transport; directed routing is inherently sequential. Use sequential transport with directed mode (set transport = 0).

E7xxx -- Deliberation transport (per-turn exchange)

Code Message What it means What to do
E7000 Failed to build payload for %s The engine could not build the request payload for a participant during the exchange. Check the participant's configuration; if it persists, contact support.
E7001 No response from %s A participant returned no response during the exchange. Check that participant's endpoint, API key, and the provider's status.
E7020 Failed to build moderator %s payload The engine could not build the moderator's payload. Check the moderator's configuration.
E7021 No response from moderator (%s) The moderator returned no response. Check the moderator's endpoint, API key, and connectivity.
E7030 Out of memory allocating response buffer
[SEQ] Moderator OPEN failed — aborting round
Out of memory allocating a participant response buffer. Free memory and retry. The round was aborted.
E7031 Out of memory allocating moderator response buffer
[SEQ] Moderator CLOSE failed — aborting round
Out of memory allocating the moderator response buffer. Free memory and retry. The round was aborted.
E7032 [SEQ] Moderator CLOSE_FINAL failed The moderator's final closing step failed in sequential mode. Check the moderator's endpoint and review the engine.log.
E7033 [SEQ] Participant '%s' failed — aborting session A participant failed during the exchange, so the session was aborted. Check that participant's provider and review the engine.log.
E7034 [DIRECTED] Participant '%s' failed — aborting session A participant failed in directed mode, so the session was aborted. Check that participant's provider and review the engine.log.
E7060 Out of memory allocating route response buffer Out of memory allocating the routing response buffer in directed mode. Free memory and retry.
E7061 Failed to build moderator ROUTE payload The engine could not build the moderator's routing payload in directed mode. Check the moderator's configuration.
E7062 No response from moderator (ROUTE) The moderator returned no response to a routing request in directed mode. Check the moderator's endpoint and connectivity.
E7070 [DIRECTED] No AI moderator configured — directed mode requires an AI moderator. Aborting round. Directed mode requires an AI moderator and none is configured. Configure an AI moderator in the session config to use directed mode.
E7071 [DIRECTED] Moderator ROUTE failed — ending round The moderator's routing step failed in directed mode, so the round ended. Check the moderator's endpoint and review the engine.log.
E7077 [DIRECTED] Moderator CLOSE retry %d failed
[DIRECTED] Moderator CLOSE failed
A moderator closing retry failed in directed mode. Usually transient. Review the log and check the moderator's provider.
E7078 [DIRECTED] Moderator CLOSE_FINAL failed The moderator's final closing step failed in directed mode. Check the moderator's endpoint and review the engine.log.
E7101 PAR out of memory Out of memory in the parallel transport. Free memory and retry.
E7120 Empty response from %s A participant returned an empty response in parallel transport. Check that participant's endpoint, key, and provider status.
E7121 HTTP %ld from %s A provider returned an HTTP error status in parallel transport. Check the endpoint, key, and rate limits.
E7122 Failed to extract text from %s response The engine could not extract text from a provider's parallel response. The provider returned an unexpected format. Verify the model and retry.
E7130 Failed to allocate parallel slots The engine could not allocate the parallel request slots. Free memory and retry; reduce the number of participants if it persists.
E7131 curl_multi_init failed (internal) The parallel HTTP driver failed to initialize. Diagnostic, usually an environment problem. Contact support if it persists.
E7132 Failed to build payload for %s The engine could not build the request payload for a participant in parallel transport. Check the participant's configuration; if it persists, contact support.
E7133 Out of memory for response buffer Out of memory for a response buffer in parallel transport. Free memory and retry.
E7134 curl_easy_init failed for %s (internal) The engine could not initialize a request handle for a participant in parallel transport. Diagnostic, usually an environment problem. Contact support if it persists.
E7135 curl_multi_wait error: %s The parallel HTTP driver reported a wait error. Usually transient. Check connectivity and retry.
E7136 [PAR] %s failed — ending session A participant failed in parallel transport, so the session was ended. Check that participant's provider and review the engine.log.
E7137 Failed to store message for %s The engine could not store a participant's message. Check free disk space and permissions on the session directory.
E7138 [PAR] Human %s failed — ending session A human participant failed in parallel transport, so the session was ended. Human participants are not supported in V1. Remove human participants; all participants must be AI models.
E7139 Out of memory for request body (%s) Out of memory building a request body in parallel transport. Free memory and retry.
E7140 Failed to build moderator %s payload
Failed to build request body (%s)
The engine could not build the moderator's payload in parallel transport. Check the moderator's configuration.
E7141 Moderator %s HTTP send failed Sending the moderator's request failed in parallel transport. Check connectivity and the moderator's endpoint.
E7142 Failed to store moderator %s turn The engine could not store the moderator's turn. Check free disk space and permissions on the session directory.
E7143 Moderator OPEN failed — aborting round The moderator's opening step failed, so the round was aborted. Check the moderator's endpoint and review the engine.log.
E7144 Moderator CLOSE failed — aborting round The moderator's closing step failed, so the round was aborted. Check the moderator's endpoint and review the engine.log.

E8xxx -- Licensing, signatures, phone-home, state, and web server

Code Message What it means What to do
E8000 License file not found: %s
Cannot find license.key in any default location.
License file not found: %s: %s
No license file was found. Provide the license with --license-key, set MCS_LICENSE_KEY, or place license.key in one of the default locations named in the hint lines.
E8001 License file missing required fields (schema v%d expected)
License seats must be >= 1, got %d
The license is missing required fields or has an invalid seat count. Obtain a valid license from osinix.com.
E8002 License signature invalid The license signature did not verify, which means the file was altered or is corrupt. Use an unmodified license issued by osinix.com.
E8003 License expired %d days ago The license has passed its expiry date. Renew your license at osinix.com.
E8004 Unknown tier: %s The license names a tier the engine does not recognize. Use a license issued for this build; if it persists, contact support.
E8005 License schema version %d not supported (this build expects v%d) The license schema version does not match what this build expects. Use a license issued for this generation of the engine.
E8010 Failed to decode signature (internal) An internal step of signature verification (decoding the signature) failed. Diagnostic, usually a corrupt license. Contact support with the full line.
E8011 BIO_new_mem_buf failed (internal) An internal cryptography step failed while reading the public key. Diagnostic. Contact support with the full line.
E8012 PEM_read_bio_PUBKEY failed (internal) An internal cryptography step failed while parsing the public key. Diagnostic. Contact support with the full line.
E8013 EVP_MD_CTX_new failed (internal) An internal cryptography step failed while preparing signature verification. Diagnostic. Contact support with the full line.
E8014 EVP_DigestVerifyInit failed: %d (internal) An internal cryptography step failed while initializing signature verification. Diagnostic. Contact support with the full line.
E8020 License allows max %d participants (%s tier). Requested: %d The session has more participants than your license allows. Reduce the participant count, or upgrade to a tier with a higher limit.
E8101 Cannot open state file for write: %s: %s
Cannot rename %s to %s: %s
The engine could not write its internal state file. Check permissions and free space on the state directory.
E8102 Cannot create state directory %s: %s The engine could not create its state directory. Check permissions on the parent directory.
E8201 license server reply too large (> %d bytes) The license server's reply was larger than allowed. Usually transient or a network intermediary problem. Retry; contact support if it persists.
E8202 out of memory parsing server reply The engine ran out of memory parsing the license server's reply. Free memory and retry.
E8203 failed to build check-in request (internal) The engine could not build the license check-in request. Diagnostic. Contact support if it persists.
E8204 curl_easy_init failed (internal) The network library could not initialize for the license check. Diagnostic, usually an environment or TLS issue. Contact support if it persists.
E8205 license server unreachable: %s The license server could not be reached for the periodic check. Check your internet connection and DNS. The engine tolerates brief outages through an offline grace period, so a single occurrence is rarely fatal.
E8206 license server returned HTTP %ld The license server returned an HTTP error. Usually transient. Retry; contact support with the status code if it persists.
E8207 malformed license server reply The license server's reply could not be parsed. Usually transient. Retry; contact support if it persists.
E8208 reply fields too long to verify The license server's reply fields were too long to verify. Usually transient or an intermediary altering the reply. Retry; contact support if it persists.
E8209 license server reply signature invalid
license server reply signature too large to cache
The license server's reply failed signature verification, or its signature was too large to cache. Usually transient. Retry; if it persists, your connection may be intercepted. Contact support.
E8300 Cannot create socket: %s The web interface could not create its network socket. Usually an operating-system or permission issue. Check that security software is not blocking the engine, then retry.
E8301 No free port in range %d-%d The web interface found no free port in its scan range (8700-8799). Another program is likely using those ports. Close conflicting services, or retry.
E8302 Cannot listen: %s The web interface could not listen on its socket. Usually a port-in-use or permission issue. Retry; check for a conflicting service if it persists.
E8303 Accept failed: %s The web interface failed to accept an incoming browser connection. Usually transient. Retry; check local networking if it persists.

E9xxx -- Engine-info file and argument handling (internal)

Code Message What it means What to do
E9000 Unknown argument: %s An unrecognized command-line argument was given. Check the flags you passed; run with --help to see valid options.
E9001 mcs_engine_info_write: NULL session
mcs_engine_info_write: session_dir empty (mcs_session_create did not populate it?)
(internal) Internal: the engine-info writer was called with no session. Diagnostic; you are unlikely to see this. Contact support if it appears.
E9002 mcs_engine_info_write: primary path overflow (session_dir too long)
mcs_engine_info_write: cannot open %s for writing: %s
mcs_engine_info_write: write failed for %s: %s
mcs_engine_info_write: fclose failed for %s: %s
Internal: the engine-info file path was too long to write. Use a shorter session directory path.
E9003 mcs_engine_info_write: tmp path overflow (skipping transient copy)
mcs_engine_info_write: cannot open %s for writing: %s (transient copy skipped)
mcs_engine_info_write: write failed for %s: %s (transient copy may be partial)
mcs_engine_info_write: fclose failed for %s: %s
(internal) Internal: the temporary engine-info file path was too long, so a transient copy was skipped. Use a shorter session directory path. Usually harmless.
E9004 mcs_engine_info_unlink_tmp: unlink %s failed: %s (internal) Internal: a temporary engine-info file could not be removed. Usually harmless. Diagnostic.

Download PDF   All docs