Search...:Error(3pm)

✨ Search::Elasticsearch::Error — the tea on errors ✨

okay so bestie, this is the page for Search...:Error(3pm), which lives in the Perl user-contributed docs, and it's literally all about the error objects that Search::Elasticsearch throws at you when things go sideways. 💖

---

💜 VERSION

version 8.12 — yes she's on 8.12, periodt.

---

🦋 DESCRIPTION

So here's the vibe: errors thrown by Search::Elasticsearch aren't just sad little strings, they're error objects. That means they can carry a whole stack trace plus extra info to help you debug what went wrong. Main character energy for an exception, honestly.

An error object is made up of this:

{
    type  => $type,              # eg Missing
    text  => 'Error message',
    vars  => {...},              # vars which may help to explain the error
    stack => [...],              # a stack trace
}

Also!! There's a $Search::Elasticsearch::Error::DEBUG variable and you can set it to 1 or 2 if you want your errors to be more verbose. Turn it up, get more detail. Slay. 🔥

Error objects also stringify into a human readable error message whenever they're used in text context (for example: "print 'Oh no! '.$error"). And they support the TO_JSON method so they can get converted to JSON when convert_blessed in JSON is enabled. Versatile queen. ✨

---

👑 ERROR CLASSES

These are all the error classes that are defined, and bestie, there are a lot of them:

• Search::Elasticsearch::Error::Param — a bad parameter got passed to a method. Rude of you tbh. 🙈
• Search::Elasticsearch::Error::Request — something generically went wrong while doing your request in Elasticsearch. This one gets triggered by HTTP status codes 400 and 500. And she has sub-classes, of course she does:
  • Search::Elasticsearch::Error::Unauthorized — invalid (or just plain missing) username/password given as "userinfo" for a password protected service. Triggered by the 401 HTTP status code.
  • Search::Elasticsearch::Error::Missing — the resource you asked for was not found. Triggered by the 404 HTTP status code.
  • Elastisearch::Error::Conflict — your request couldn't be performed because of some conflict. Like, say you try to delete a document with a particular version number but the document already changed — boom, you get a Conflict error. If it can, it'll include the current_version in the error vars. This one is triggered by the 409 HTTP status code.
  • Search::Elasticsearch::Error::ContentLength — the request body was longer than the max_content_length. Too much. 💀
  • Search::Elasticsearch::Error::RequestTimeout — the request took longer than the specified "timeout". Currently this only applies to the cluster_health request.
• Search::Elasticsearch::Error::Timeout — the request timed out. She simply could not wait any longer. ⏰
• Search::Elasticsearch::Error::Cxn — there was an error connecting to a node in the cluster. This one means node failure, and it will get retried on another node. She's got sub-classes too:
  • Search::Elasticsearch::Error::Unavailable — the current node can't handle your request right now, so your request gets retried on another node. Triggered by the 503 HTTP status code.
  • Search::Elasticsearch::Error::BadGateway — a proxy sitting between the client and Elasticsearch can't connect to Elasticsearch. Triggered by the 502 HTTP status code.
  • Search::Elasticsearch::Error::GatewayTimeout — a proxy between the client and Elasticsearch can't connect to Elasticsearch within its own timeout. Triggered by the 504 HTTP status code.
  • Search::Elasticsearch::Error::SSL — there was a problem validating the SSL certificate. Heads up: not all backends support this error type. 🫶
• Search::Elasticsearch::Error::Forbidden — either the cluster couldn't process the request because it's currently blocking (like, there aren't enough master nodes to form a cluster), or the authenticated user is trying to do an unauthorized action. Triggered by the 403 HTTP status code.
• Search::Elasticsearch::Error::Illegal — you attempted an illegal operation. For instance, you tried to use a Scroll helper in a different process after forking. Not the move. 😭
• Search::Elasticsearch::Error::Serializer — there was an error serializing a variable or deserializing a string.
• Elasticsarch::Error::Internal — an internal error occurred, so please report this as a bug in this module. Tell the devs!! 🐛

---

🌸 AUTHOR

Enrico Zimuel <enrico.zimuel@elastic.co> — thank you king 💜

---

🎀 COPYRIGHT AND LICENSE

This software is Copyright (c) 2024 by Elasticsearch BV.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

and that's the whole page bestie, no cap. go forth and catch your errors with grace. 🌈✨

perl v5.38.2 · 2024-02-04 · Search...:Error(3pm) — mwah, bye! 💅🎀🦋