Skip to Content
ContentTroubleshooting

Troubleshooting

Common issues and their solutions when working with Hero Hook Form.

💡 Tip

Most issues can be resolved by checking field names match your schema, ensuring providers are set up correctly, and verifying TypeScript types are correct.

Quick Reference

Common Symptoms

  • RHF type mismatch - Field names or defaultValues don’t match schema/type
  • Errors not visible - Custom UI doesn’t render error props
  • Server errors not applied - Errors not mapped back to RHF

See detailed solutions below.

Form Not Rendering

⚠️ Warning

If your form isn’t rendering, check that you’ve wrapped your app with the provider and that field configurations are correct.

Symptom

Form fields are not appearing or form is blank.

Cause

Missing HeroHookFormProvider wrapper or incorrect field configuration.

Fix

// Wrap your app with the provider
import { HeroHookFormProvider } from "@rachelallyson/hero-hook-form";
 
function App() {
  return (
    <HeroHookFormProvider>
      <YourForms />
    </HeroHookFormProvider>
  );
}
 
// Ensure proper field configuration
const fields = [
  {
    name: "email",
    type: "input",
    label: "Email",
  },
];

TypeScript Errors

ℹ️ Info

TypeScript errors usually indicate a mismatch between your schema, field names, or types. Use Zod inference for automatic type safety.

Symptom

TypeScript compilation errors with form types.

Cause

Missing type definitions or incorrect generic usage.

Fix

// ✅ Recommended: Use Zod inference
const schema = z.object({
  name: z.string(),
  email: z.string().email(),
  message: z.string(),
});
 
type ContactFormData = z.infer<typeof schema>;
 
// Or define manually
interface ContactFormData {
  name: string;
  email: string;
  message: string;
}
 
// Use with form
const form = useForm<ContactFormData>();
💡 Tip

Using Zod schema inference ensures your types always match your validation rules.

Validation Not Working

⚠️ Warning

If validation isn’t working, make sure you’ve provided a Zod schema and resolver, or React Hook Form validation rules.

Symptom

Form validation is not triggering or error messages not showing.

Cause

Missing Zod schema or incorrect resolver setup.

Fix

import { zodResolver } from "@hookform/resolvers/zod";
 
const form = useForm({
  resolver: zodResolver(schema), // Add resolver
  mode: "onBlur", // Trigger validation on blur
});
 
// Ensure schema is properly defined
const schema = z.object({
  email: z.string().email("Invalid email"),
});
💡 Tip

For ZodForm, the resolver is automatically set up. For ConfigurableForm, you need to provide validation rules or a resolver manually.

Field Not Updating

Symptom

Field values are not updating when user types.

Cause

Missing onValueChange handler or incorrect field configuration.

Fix

// Use proper field configuration
const fields = [
  {
    name: "email",
    type: "input",
    label: "Email",
    inputProps: {
      type: "email",
    },
  },
];
 
// Or use helper functions
const fields = [
  FormFieldHelpers.input("email", "Email", "email"),
];

Server Errors Not Displaying

Symptom

Server validation errors are not showing in the form.

Cause

Not using applyServerErrors or incorrect error format.

Fix

import { applyServerErrors } from "@rachelallyson/hero-hook-form";
 
const handleSubmit = async (data) => {
  try {
    const response = await fetch("/api/submit", {
      method: "POST",
      body: JSON.stringify(data),
    });
 
    if (!response.ok) {
      const errorData = await response.json();
      // Apply server errors to form
      applyServerErrors(form.setError, {
        fieldErrors: errorData.fieldErrors,
      });
    }
  } catch (error) {
    console.error("Error:", error);
  }
};
ℹ️ Info

Server errors must be in the format: { fieldErrors: [{ path: "fieldName", message: "Error message" }] }

Performance Issues

Symptom

Form is slow or laggy with many fields.

Cause

Missing memoization or excessive re-renders.

Fix

import { memo } from "react";
 
// Field components are already memoized, but you can memoize custom components
const MemoizedField = memo(InputField);
 
// Use debounced validation
import { useDebouncedValidation } from "@rachelallyson/hero-hook-form";
 
const { debouncedTrigger } = useDebouncedValidation(form, { delay: 300 });

Conditional Fields Not Working

Symptom

Conditional fields are not showing/hiding properly.

Cause

Incorrect condition function or missing dependencies.

Fix

// Ensure condition function is correct
ConditionalField({
  name: "phone",
  label: "Phone",
  type: "input",
  condition: (values) => values.hasPhone === true, // Explicit comparison
});
 
// Check dependencies
const fields = [
  FormFieldHelpers.checkbox("hasPhone", "Has Phone"),
  ConditionalField({
    name: "phone",
    label: "Phone",
    type: "input",
    condition: (values) => values.hasPhone,
  }),
];
💡 Tip

Always use explicit boolean comparisons (=== true) in conditions to avoid truthy/falsy issues.

Field Array Issues

Symptom

Field arrays are not adding/removing items correctly.

Cause

Incorrect field array configuration or missing keys.

Fix

// Ensure proper field array configuration
FieldArrayField({
  name: "addresses",
  fields: [
    FormFieldHelpers.input("street", "Street"),
    FormFieldHelpers.input("city", "City"),
  ],
  addButtonText: "Add Address",
  removeButtonText: "Remove Address",
  min: 1,
  max: 5,
});
 
// Use proper keys in rendering
{fields.map((field, index) => (
  <FormField
    key={`${field.name}-${index}`} // Unique key
    config={field}
    form={form}
  />
))}

Styling Issues

Symptom

Form fields don’t match HeroUI styling.

Cause

Missing HeroUI provider or incorrect CSS imports.

Fix

// Ensure HeroUI provider is set up
import { HeroUIProvider } from "@heroui/react";
 
function App() {
  return (
    <HeroUIProvider>
      <HeroHookFormProvider>
        <YourForms />
      </HeroHookFormProvider>
    </HeroUIProvider>
  );
}
 
// Import HeroUI styles
import "@heroui/react/dist/index.css";

Testing Issues

Symptom

Form tests are failing or not working properly.

Cause

Missing test utilities or incorrect test setup.

Fix

import { createFormTestUtils } from "@rachelallyson/hero-hook-form";
 
// Create test utilities
const testUtils = createFormTestUtils(form);
 
// Use proper test methods
await testUtils.submitForm();
const fieldValue = testUtils.getField("fieldName");
testUtils.setFieldValue("fieldName", "new value");

Common Error Messages

”Cannot read property ‘register’ of undefined”

Fix: Ensure form is properly initialized with useForm().

”Field ‘name’ is required”

Fix: Add name property to field configuration.

”Schema validation failed”

Fix: Check Zod schema definition and error messages.

”Component is not a function”

Fix: Ensure proper imports and component registration.

Getting Help

If you’re still experiencing issues:

  1. Check the API Reference for detailed documentation
  2. Look at the Examples for working code
  3. Check the FAQ for common questions
  4. Search GitHub Issues 
  5. Create a new issue with:
    • Code example
    • Error message
    • Expected behavior
    • Actual behavior
ℹ️ Info

When reporting issues, include a minimal code example that reproduces the problem. This helps us diagnose and fix issues faster.

Next Steps

Last updated on
ConfigurationIndex