Troubleshooting & FAQ

This chapter collects common questions and issues so you can solve most problems yourself without contacting support.

If you do end up needing help, having worked through these steps will also make it easier for support to assist you quickly.

Login and Account Issues

“Failed to connect to API server”

Symptom:

• On the login screen, you see an error like:

  Failed to connect to API server at [::1]:50051 …

What it means:

• The backend API server is not running or not reachable from your machine.

What to do:

• Check your internet connection.
• If you know you should be connecting to a local deployment, ensure your BinaryCircuits admin has started the API server.
• If the problem persists, forward the full error message to your admin or support.

“Login failed” or “No access token received”

Symptom:

• After entering email/password and pressing Enter, you see an error message and stay on the login screen.

Possible causes:

• Email or password typo.
• Your account doesn’t exist yet (try registering).
• The server had an internal error.

What to do:

• Double‑check your email and password.
• If you are new, use the Register mode (press Tab to switch) to create an account.
• If the error message mentions a server issue, try again later or contact support with the exact text.

“I want to log out everywhere”

Symptom:

• You want to ensure you’re logged out and your session is cleared on your machine.

What to do:

• Use any in‑app logout option if present.

• If you want to force a local logout:

  rm ~/.matrixforge/session.json
  

• Next time you start the app, you’ll be asked to log in again.

Marketplace and Purchases

“The marketplace is empty”

Symptom:

• The Browse screen shows no workflows, or you repeatedly see “Failed to load workflows”.

Possible causes:

• Connection problems to the API.
• Misconfigured filters (in future releases).
• Server‑side issues.

What to do:

• Confirm you are logged in.
• Look at any error message at the bottom of the screen for more details.
• If the error mentions network or server problems, contact your admin or support with the message.

“I can’t add a workflow to my cart”

Symptom:

• Pressing a does nothing, or you see “Already in cart”.

What to do:

• Check whether the workflow is already in your cart:
  • Press 3 to go to the Cart screen and review the items.
• If it is already there, you do not need to add it again.

“Checkout failed”

Symptom:

• After confirming purchase in the Cart, you see an error like “Purchase failed: …”.

Possible causes:

• Payment provider rejected the transaction.
• Your subscription tier does not allow purchasing this workflow.
• Temporary server issue.

What to do:

• Note the exact error message.
• Verify that your subscription tier should allow the purchase (see the Pricing chapter).
• Try again once; if it still fails, contact support with:
  • The workflow name.
  • The approximate time.
  • The full error message shown.

Workflows and Execution

“How do I know if a workflow is compilable?”

Answer:

• In the Browse and Details screens you’ll see a Compilation section or a “Compilable ✓” indicator.
• If a workflow is marked as not compilable, it typically means:
  • It uses nodes that the compiler does not support yet, or
  • There were validation issues.

For such workflows, you can:

• Watch for updates from the author.
• Request support for missing nodes via the platform’s node request system (where available).

“My compiled workflow runs but produces no output”

Possible causes:

• The workflow is designed to perform side‑effects only (for example, send an email), not return a JSON payload.
• The workflow expects specific input and quietly exits if conditions are not met.

What to do:

• Re‑read the workflow description to see what it claims to do.
• Check any provided usage examples to ensure:
  • Your input JSON matches what it expects.
  • Any required environment variables or credentials are set.

If it still seems wrong, contact the workflow author or support with:

• The workflow name and version.
• The exact command you ran.
• A sample of your input JSON (with sensitive data redacted).

“The workflow is slow”

Possible causes:

• Heavy external API calls (for example, large AI models, third‑party services).
• Large data sets flowing through nodes.
• Network latency in your environment.

What to do:

• If possible, test on a machine closer to the services it calls.
• Use traces (see “Working With Workflows” chapter) to identify which parts of the workflow are slow.
• If a particular workflow is consistently slow for all users, raise it with the workflow author or support.

Pricing, Tiers, and Licensing

“Why can’t I access a particular workflow?”

Possible reasons:

• Your subscription tier does not include workflows at that price level or category.
• The workflow has been restricted to higher‑tier users or is part of a special offer.

What to do:

• Check your current tier (visible in your account area or from your admin).
• Review the Pricing & Subscriptions chapter to see which tiers can access which workflows.
• Consider:
  • Upgrading your subscription, or
  • Purchasing the workflow individually if offered a la carte.

“Will my binaries stop working if I cancel my subscription?”

Answer:

• No. Compiled binaries you already have will continue to run.
• Cancelling or downgrading affects:
  • Your ability to compile new workflows.
  • Your access to certain marketplace content.
  • Your support level.

You retain the right to run existing binaries indefinitely, subject to any local laws or agreements you must follow.

When to Contact Support

If you have worked through the relevant sections of this guide and still have issues, it’s time to contact support. To make the process faster, include:

• Your account email and subscription tier.
• The workflow name and version (if applicable).
• A clear description of:
  • What you tried to do.
  • What you expected to happen.
  • What actually happened (including any error messages).
• The approximate time the issue occurred.

Use:

• Community channels for general “how do I…?” questions.
• Email support (if your tier includes it) for account, billing, or platform problems.
• The security reporting address for anything that looks like a security vulnerability.

The more detail you provide up front, the fewer back‑and‑forth messages will be needed to resolve your issue.