Troubleshooting

Quick reference for common issues across joins, grouping, presets, curation, CLI, DX, schema, indexer, testing, observability, and deletion.

Quick reference for common issues. Each section links to deeper docs.

Related: Observability, CLI, Testing

Joins

• Missing or invalid association name
  • Ensure you declared it on the model with belongs_to :name, has_one :name, or has_many :name
  • See Joins → DSL
• Joined fields not appearing in selection
  • Use nested include fields and prefix joined fields with $assoc.field
  • See Field selection

Grouping

• group_limit ignored
  • Provide a positive integer; omitted when nil
  • See Grouping → Mapping
• Unexpected missing‑values behavior
  • Set missing_values: true explicitly
  • See Grouping → State → Params

Presets

• Defaults not applied
  • Confirm default_preset on the model and presets.enabled
  • See Presets → Config & Default
• :lock mode not locking as expected
  • Check locked_domains normalization and compiler pruning
  • See Presets → Modes

Curation

• Hidden IDs still visible
  • Ensure filter_curated_hits is set when you want hidden hits excluded
  • See Curation → DSL
• Order of pinned hits unstable
  • Pin order is first‑occurrence; avoid duplicates
  • See Curation → Inspect/explain

CLI

• Task arguments parsed incorrectly
  • Quote args and avoid spaces inside brackets
  • See CLI → Usage
• doctor exits with 1
  • Run with VERBOSE=1 or FORMAT=json for details
  • See CLI → Doctor flow

DX

• to_curl shows API key
  • Keys are redacted; update to latest, or file an issue with a snippet
  • See DX
• dry_run! performs I/O
  • dry_run! compiles only; check for accidental client calls
  • See DX → Helpers

Schema

• Drift not detected
  • Use aliases correctly; compare compiled vs active physical
  • See Schema → Diff
• Rollback unavailable
  • Retention may be insufficient; ensure previous physical retained
  • See Schema → API

Indexer

• 413 Payload Too Large
  • Batches split recursively; reduce batch_size
  • See Indexer → Retries & backoff
• Memory spikes
  • Ensure streaming JSONL and avoid materializing large arrays
  • See Indexer → Memory notes

Testing

• Stub not capturing calls
  • Ensure SearchEngine.config.client = SearchEngine::Test::StubClient.new
  • Explicit SearchEngine.config.client always takes precedence over offline mode
  • See Testing → Quick start
• Test mode not working as expected
  • Verify test_mode is enabled: SearchEngine.config.test_mode? should return true in test environment
  • Check environment: Rails.env.test? or RACK_ENV=test enables test mode automatically
  • Override via SEARCH_ENGINE_TEST_MODE=1 or SEARCH_ENGINE_OFFLINE=1 (legacy alias)
  • Use SearchEngine.client to access the configured client instance
  • Note: if SearchEngine.config.client is explicitly set, it always wins
  • See Testing → Test mode

Observability

• Missing events
  • Wrap calls with instrumentation helpers and enable subscriber
  • See Observability → Events
• Too much PII in logs
  • Redaction rules mask secrets and filter literals; use params_preview
  • See Observability → Redaction rules

Deletion

• No effect / deleted 0 docs
  • Verify into: points to the intended physical (or rely on alias)
  • Ensure filter is correct; try rel.dry_run! first to preview
  • See Deletion
• Empty input error
  • delete_by requires a non-blank String or a non-empty Hash
  • See Deletion → Model-level
• Model.cleanup or index:delete_stale skipped
  • Ensure you declared stale rules inside index; otherwise cleanup logs a skip and returns 0
  • Remember rules are OR‑ed; verify at least one resolves to a non‑empty filter for the given partition

Error Reference

The gem provides a structured error hierarchy under SearchEngine::Errors.

Error	Description	Action
Timeout	Request exceeded timeout_ms.	Check network or increase timeout.
Connection	DNS/Socket failure.	Check host availability.
Api	Non-2xx response from Typesense.	Check error.status and error.body.
InvalidParams	Missing or invalid inputs.	Fix arguments provided to method.
InvalidField	Field not in schema (and strict mode on).	Add field to schema or disable strict_unknown_keys.
UnknownField	Field referenced in selection not declared on model.	Add attribute declaration or fix typo.
InvalidOperator	Operator not recognized by query parser.	Use supported operators (see Query DSL).
InvalidType	Value cannot be coerced to declared type.	Fix value type or enable coercions.
InvalidSelection	Materializer requests fields not permitted by selection.	Adjust relation’s select/exclude or materializer.
MissingField	Hydration missing required field.	Ensure API returns field or mark optional.
ConflictingSelection	Selection inputs are malformed or ambiguous.	Normalize selection inputs.
InvalidGroup	Grouping DSL used with invalid inputs.	Fix field names, limits, or missing_values.
UnsupportedGroupField	Grouping references joined/path fields.	Use base fields only for grouping.
HitLimitExceeded	Result count > max validation.	Narrow query or increase limit.