stablyai/orca · error · RuntimeClientError

linear_invalid_url

linear_invalid_url

Error message

--url must be an absolute http(s) URL

What it means

Thrown by getHttpUrlFlag when the `--url` flag (or any flag routed through this helper) is not an absolute http: or https: URL. The URL is parsed with `new URL(value)`; if parsing throws or the protocol is anything other than http/https (e.g. file:, ftp:, or a bare string), the error is raised. The parse failure is intentionally swallowed so the user sees the stable Linear error rather than a Node URL exception.

Source

Thrown at src/cli/linear-request-builders.ts:222

  }
  const writeId = getRequiredStringFlag(flags, 'write-id')
  if (!isLinearUuid(writeId)) {
    throw new RuntimeClientError('linear_invalid_write_id', '--write-id must be a UUID')
  }
  return writeId
}

export function getHttpUrlFlag(flags: Map<string, string | boolean>, name: string): string {
  const value = getRequiredStringFlag(flags, name)
  try {
    const parsed = new URL(value)
    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
      return value
    }
  } catch {
    // Fall through to the stable Linear error below.
  }
  throw new RuntimeClientError('linear_invalid_url', '--url must be an absolute http(s) URL')
}

export function readLinearBody(
  flags: Map<string, string | boolean>,
  cwd: string,
  options: { required: true }
): Promise<string>
export function readLinearBody(
  flags: Map<string, string | boolean>,
  cwd: string,
  options: { required: false }
): Promise<string | undefined>
export async function readLinearBody(
  flags: Map<string, string | boolean>,
  cwd: string,
  options: { required: boolean }
): Promise<string | undefined> {
  const hasBody = flags.has('body')

View on GitHub (pinned to 1136503c6a)

Solutions

1. Prefix the value with `https://`: `--url https://linear.app/issue/LIN-123`.
2. Verify the value with `new URL(value)` in a preflight check before invoking the CLI.
3. Ensure env vars feeding `--url` are non-empty and include the scheme.

Example fix

// before
linear issue --url linear.app/issue/LIN-123
// after
linear issue --url https://linear.app/issue/LIN-123

function asHttpUrl(value: string): string {
  const u = new URL(value)
  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
    throw new Error(`Expected http(s) URL, got ${u.protocol}`)
  }
  return value
}
asHttpUrl(flags.get('url')!)

function isAbsoluteHttpUrl(value: string): boolean {
  try {
    const u = new URL(value)
    return u.protocol === 'http:' || u.protocol === 'https:'
  } catch {
    return false
  }
}

When it happens

Trigger: Passing a relative path (`--url /issue/123`), a bare hostname without scheme (`--url linear.app`), a non-http protocol (`--url ftp://...`), or a malformed string to a command that consumes `--url` via getHttpUrlFlag.

Common situations: Copying a URL fragment without the scheme. Assuming `//host/path` is accepted. Passing a Linear app deep link that uses a custom scheme. Env-var expansion producing an empty or partial URL.

Related errors

• invalid_argument
• invalid_argument
• linear_invalid_workspace
• linear_issue_required
• linear_invalid_write_id

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/883cb9261afeed37. Report an issue: GitHub.