actualbudget/actual · warning

Missing url parameter

Error message

Missing url parameter

What it means

The CORS proxy endpoint requires the target address to be supplied as the `url` query parameter. If the query string has no url parameter (or it is empty), the proxy immediately responds 400 with error 'Missing url parameter'. This is a cheap pre-check performed before session validation and allowlist checks.

Source

Thrown at packages/sync-server/src/app-cors-proxy.js:132

    console.warn('Invalid target URL:', targetUrl, e.message);
    return false;
  }
}

app.use('/', async (req, res) => {
  // CORS preflight
  if (req.method === 'OPTIONS') {
    res.set('Access-Control-Allow-Origin', '*');
    res.set('Access-Control-Allow-Methods', 'GET,HEAD,OPTIONS');
    res.set('Access-Control-Allow-Headers', 'Content-Type, X-Actual-Token');
    res.set('Access-Control-Max-Age', '600');
    return res.status(204).end();
  }

  const targetUrlString = req.query.url;

  if (!targetUrlString) {
    return res.status(400).json({ error: 'Missing url parameter' });
  }

  // Validate session/token
  const session = await validateSession(req, res);
  if (!session) {
    return; // validateSession already sent the response
  }

  let url;
  try {
    url = new URL(targetUrlString);
  } catch {
    return res.status(400).json({ error: 'Invalid url parameter' });
  }

  // Fetch the latest allowlist
  try {
    await fetchAllowlist();

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Append the target URL as a properly encoded query parameter: /cors-proxy?url=<encodeURIComponent(target)>.
2. Use the provided client-side proxy helper if available instead of hand-building the request.
3. Verify the request method/path matches what the plugin code expects (query param, not body field).

Example fix

// before
fetch('/cors-proxy', { method: 'GET' });
// after
fetch(`/cors-proxy?url=${encodeURIComponent('https://example.com/list.json')}`);

if (!target) throw new Error('cors-proxy requires a target url');
const qs = `?url=${encodeURIComponent(target)}`;

try {
  return await fetch(`/cors-proxy?url=${encodeURIComponent(target)}`);
} catch (e) {
  if (e.status === 400) console.error('Check the proxy request: url query param required');
  throw e;
}

When it happens

Trigger: GET/POST to /cors-proxy without ?url=<encoded-url>, or with url= empty, e.g. calling the proxy endpoint directly without building the query string.

Common situations: Forgetting encodeURIComponent so a bare URL breaks the query string; constructing the request manually instead of using the client helper; proxy path hit by a health check or crawler without parameters.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Invalid method parameter
• Invalid url parameter
• Invalid --name: must be a non-empty string.
• No update fields provided. Use --name or --offbudget.
• Invalid cutoff date: expected a valid date (e.g. YYYY-MM-DD)

AI-assisted analysis of actualbudget/actual@d4334cb6e6 (2026-08-29). Data as JSON: /api/errors/5d2a39711b786dc9. Report an issue: GitHub.