Mintplex-Labs/anything-llm · error

URI must start with '${this.scheme}://'

Error message

URI must start with '${this.scheme}://'

What it means

Thrown by ConnectionStringParser.parse when the URI does contain a scheme but it differs from the scheme the parser instance was constructed with. Unlike the no-scheme case, parsing succeeded far enough to extract tokens[1]; the mismatch check then rejects it so a MySQL-typed parser never hands back a PostgreSQL-shaped object.

Source

Thrown at server/utils/agents/aibitat/plugins/sql-agent/SQLConnectors/utils.js:110

        "(?:([^:@,/?=&]+)(?::([^:@,/?=&]+))?@)?" + // User (Group 2) and Password (Group 3)
        "([^@/?=&]+)" + // Host address(es) (Group 4)
        "(?:/([^:@,/?=&]+)?)?" + // Endpoint (Group 5)
        "(?:\\?([^:@,/?]+)?)?" + // Options (Group 6)
        "\\s*$", // Optional whitespace padding at the end of the line
      "gi"
    );
    const connectionStringObject = {};

    if (!uri.includes("://")) {
      throw new Error(`No scheme found in URI ${uri}`);
    }

    const tokens = connectionStringParser.exec(uri);

    if (Array.isArray(tokens)) {
      connectionStringObject.scheme = tokens[1];
      if (this.scheme && this.scheme !== connectionStringObject.scheme) {
        throw new Error(`URI must start with '${this.scheme}://'`);
      }
      connectionStringObject.username = tokens[2]
        ? decodeURIComponent(tokens[2])
        : tokens[2];
      connectionStringObject.password = tokens[3]
        ? decodeURIComponent(tokens[3])
        : tokens[3];
      connectionStringObject.hosts = this._parseAddress(tokens[4]);
      connectionStringObject.endpoint = tokens[5]
        ? decodeURIComponent(tokens[5])
        : tokens[5];
      connectionStringObject.options = tokens[6]
        ? this._parseOptions(tokens[6])
        : tokens[6];
    }
    return connectionStringObject;
  }

View on GitHub (pinned to 3aec848f28)

Solutions

  1. Align the URI scheme with the connector's expected scheme exactly (postgresql:// for PostgreSQL, mysql:// for MySQL, sqlserver:// for SQL Server per the parser's construction).
  2. Expand aliases before parsing: replace /^postgres:\/\// with 'postgresql://' and /^mssql:\/\// with 'sqlserver://'.
  3. Store engine and URI together and validate them as a pair when saving agent SQL connections.

Example fix

// before
const p = new ConnectionStringParser({ scheme: "postgresql" });
p.parse("postgres://user@host/db");  // throws: URI must start with 'postgresql://'

// after
p.parse("postgresql://user@host/db");
Defensive patterns

Strategy: validation

Validate before calling

const SCHEME_ALIASES = { postgres: "postgresql", mssql: "sqlserver", "sql-server": "sqlserver" };
function normalizeUriScheme(uri, expected) {
  let u = uri.trim();
  const m = u.match(/^([a-z-]+):\/\//i);
  if (!m) throw new Error(`No scheme found in URI ${u}`);
  const canonical = SCHEME_ALIASES[m[1].toLowerCase()] ?? m[1].toLowerCase();
  if (canonical !== expected) throw new Error(`URI scheme '${m[1]}' does not match connector '${expected}'`);
  return canonical + "://" + u.slice(m[0].length);
}

Type guard

/** @returns {boolean} */
function uriStartsWithScheme(uri, scheme) {
  return typeof uri === "string" && uri.trim().toLowerCase().startsWith(`${scheme}://`);
}

Try / catch

try {
  const parsed = parser.parse(uri);
} catch (e) {
  if (e.message.includes("URI must start with")) {
    parsed = parser.parse(uri.replace(/^postgres:\/\//i, "postgresql://")); // alias fix, retry
  } else throw e;
}

Prevention

When it happens

Trigger: Parsing 'postgresql://user@host/db' with a parser built for scheme 'mysql'; a stored agent SQL connection whose engine key and connection string disagree; using scheme aliases like 'postgres://' or 'sqlserver://' against a parser expecting the canonical string.

Common situations: Switching a connection's engine in settings without updating the stored URI; aliases ('postgres' vs 'postgresql') that pass user review but fail exact comparison; mixed config sources where one field was migrated and the other was not.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@3aec848f28 (2026-08-18). Data as JSON: /api/errors/5ec9f729ea75fc2a. Report an issue: GitHub.