What causes "New user not found" in actualbudget/actual?

List users on the server (admin users endpoint) and use the exact id of an existing user.

new-user-not-found

new-user-not-found

Error message

New user not found

What it means

This 400 error is returned when the admin file-ownership endpoint is given a newUserId that passes the empty check but does not exist in the server database. UserService.getUserById returns 0 rows and the server responds with reason 'new-user-not-found'. The target user must be an existing account on this sync server.

Source

Thrown at packages/sync-server/src/app-admin.js:403

        status: 'error',
        reason: 'invalid-file-id',
        details: 'File not found at server',
      });
      return;
    }

    if (!newUserOwner.newUserId) {
      res.status(400).send({
        status: 'error',
        reason: 'user-cant-be-empty',
        details: 'Username cannot be empty',
      });
      return;
    }

    const newUserIdFromDb = UserService.getUserById(newUserOwner.newUserId);
    if (newUserIdFromDb === 0) {
      res.status(400).send({
        status: 'error',
        reason: 'new-user-not-found',
        details: 'New user not found',
      });
      return;
    }

    UserService.updateFileOwner(newUserOwner.newUserId, newUserOwner.fileId);

    res.status(200).send({ status: 'ok', data: {} });
  },
);

app.use(errorMiddleware);

View on GitHub (pinned to d4334cb6e6)

Solutions

List users on the server (admin users endpoint) and use the exact id of an existing user.
Create the user on this server first if it genuinely does not exist, then retry the ownership transfer.
Check you are not passing a username/display name where the API expects the internal user id.

Example fix

// before
await setFileOwner({ fileId, newUserId: 'alice' }); // username, not id
// after
const users = await adminListUsers();
const user = users.find(u => u.userName === 'alice');
await setFileOwner({ fileId, newUserId: user.userId });

Defensive patterns

Strategy: validation

Validate before calling

const users = await adminListUsers();
if (!users.some(u => u.userId === newUserId)) {
  throw new Error(`User ${newUserId} not found on this server`);
}

Try / catch

try {
  await setFileOwner({ fileId, newUserId });
} catch (e) {
  if (e.reason === 'new-user-not-found') {
    // create the user or pick an existing id from adminListUsers()
  }
}

Prevention

Look up user ids via the admin users endpoint instead of trusting stored/remembered ids.
Distinguish clearly between usernames and internal user ids in tooling.
Re-create users after a database reset before reassigning file ownership.

When it happens

Trigger: Calling the admin endpoint with newUserId set to a user id that was deleted, exists only on another server, or was mistyped.

Common situations: Stale user ids cached in admin tooling after the user was removed; pointing an admin script at a server where the user was never created (fresh database); id vs username confusion — passing a username where a user id is expected.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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