#Convex ents .field migration

4 messages · Page 1 of 1 (latest)

lusty baneBOT
#

Hi @misty merlin. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

The error you're seeing during your migration—Object is missing the required field email—suggests that Convex's schema validation is rejecting some imported documents because they do not match the required schema for the users table. Even though your JSONL line includes an email field, the error can occur if:

  1. Some documents in your import are missing the email field (even a single one will cause the migration to fail).
  2. The schema expects email to be a required string (not optional), so every document must have a non-null, non-undefined, non-empty string for email.

With Convex Ents, when you define a field as required and unique like this:

users: defineBaseEnt({
  firstName: v.string(),
  lastName: v.string(),
  name: v.optional(v.string()),
  emailVerified: v.boolean(),
  image: v.optional(v.string()),
})
  .field("email", v.string(), { unique: true })
  • The email field is required for every document.
  • If any document in your import is missing email, or if the value is null or undefined, the import will fail for that document.
  • If you want to allow some documents to not have an email, you must use v.optional(v.string()) for the field validator, but then you lose the guarantee that every user has an email, and uniqueness checks become more complex (see below).
#

Important note about uniqueness and optional fields:
Convex Ents' uniqueness checks can be tricky with optional fields. If you make email optional, you may run into issues where multiple documents have email unset, which can cause uniqueness errors or unexpected behavior. This is discussed in the support thread: uniqueness checks on optional fields (unset/undefined) are not always handled as you might expect, and you may get errors if more than one document has an unset value for a unique field. The recommended approach is to keep unique fields required if possible, and ensure your data always provides them during import and creation Convex Ents: Unique field values, Discord: unique() query returned more than one result.

What to do:

  • Double-check your entire JSONL file to ensure every document has a valid, non-empty email field.
  • If you want to allow missing emails, change the schema to v.optional(v.string()), but be aware of the uniqueness caveats.
  • If you want to keep email required and unique, you must ensure all imported documents have a valid email.

Summary:
The error is not due to the Convex Ents .field implementation itself, but rather to the strict schema validation: every document must match the required fields exactly. If even one document is missing email, the import will fail. Check your data and schema alignment carefully.