docs, core: error messaging [wip] (#27397)

docs/docs/troubleshooting/errors/INVALID_PROMPT_INPUT.mdx

@@ -0,0 +1,14 @@
+# INVALID_PROMPT_INPUT
+
+A [prompt template](/docs/concepts#prompt-templates) received missing or invalid input variables.
+
+## Troubleshooting
+
+The following may help resolve this error:
+
+- Double-check your prompt template to ensure that it is correct.
+  - If you are using the default f-string format and you are using curly braces `{` anywhere in your template, they should be double escaped like this: `{{` (and if you want to render a double curly brace, you should use four curly braces: `{{{{`).
+- If you are using a [`MessagesPlaceholder`](/docs/concepts/#messagesplaceholder), make sure that you are passing in an array of messages or message-like objects.
+  - If you are using shorthand tuples to declare your prompt template, make sure that the variable name is wrapped in curly braces (`["placeholder", "{messages}"]`).
+- Try viewing the inputs into your prompt template using [LangSmith](https://docs.smith.langchain.com/) or log statements to confirm they appear as expected.
+- If you are pulling a prompt from the [LangChain Prompt Hub](https://smith.langchain.com/prompts), try pulling and logging it or running it in isolation with a sample input to confirm that it is what you expect.

docs/docs/troubleshooting/errors/MESSAGE_COERCION_FAILURE.ipynb

@@ -0,0 +1,122 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# MESSAGE_COERCION_FAILURE\n",
+    "\n",
+    "Instead of always requiring instances of `BaseMessage`, several modules in LangChain take `MessageLikeRepresentation`, which is defined as:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from typing import Union\n",
+    "\n",
+    "from langchain_core.prompts.chat import (\n",
+    "    BaseChatPromptTemplate,\n",
+    "    BaseMessage,\n",
+    "    BaseMessagePromptTemplate,\n",
+    ")\n",
+    "\n",
+    "MessageLikeRepresentation = Union[\n",
+    "    Union[BaseMessagePromptTemplate, BaseMessage, BaseChatPromptTemplate],\n",
+    "    tuple[\n",
+    "        Union[str, type],\n",
+    "        Union[str, list[dict], list[object]],\n",
+    "    ],\n",
+    "    str,\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "These include OpenAI style message objects (`{ role: \"user\", content: \"Hello world!\" }`),\n",
+    "tuples, and plain strings (which are converted to [`HumanMessages`](/docs/concepts#humanmessage)).\n",
+    "\n",
+    "If one of these modules receives a value outside of one of these formats, you will receive an error like the following:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "ename": "ValueError",
+     "evalue": "Message dict must contain 'role' and 'content' keys, got {'role': 'HumanMessage', 'random_field': 'random value'}",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mKeyError\u001b[0m                                  Traceback (most recent call last)",
+      "File \u001b[0;32m~/langchain/oss-py/libs/core/langchain_core/messages/utils.py:318\u001b[0m, in \u001b[0;36m_convert_to_message\u001b[0;34m(message)\u001b[0m\n\u001b[1;32m    317\u001b[0m     \u001b[38;5;66;03m# None msg content is not allowed\u001b[39;00m\n\u001b[0;32m--> 318\u001b[0m     msg_content \u001b[38;5;241m=\u001b[39m \u001b[43mmsg_kwargs\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mpop\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mcontent\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m)\u001b[49m \u001b[38;5;129;01mor\u001b[39;00m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m    319\u001b[0m \u001b[38;5;28;01mexcept\u001b[39;00m \u001b[38;5;167;01mKeyError\u001b[39;00m \u001b[38;5;28;01mas\u001b[39;00m e:\n",
+      "\u001b[0;31mKeyError\u001b[0m: 'content'",
+      "\nThe above exception was the direct cause of the following exception:\n",
+      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[5], line 10\u001b[0m\n\u001b[1;32m      3\u001b[0m uncoercible_message \u001b[38;5;241m=\u001b[39m {\n\u001b[1;32m      4\u001b[0m     \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mrole\u001b[39m\u001b[38;5;124m\"\u001b[39m: \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mHumanMessage\u001b[39m\u001b[38;5;124m\"\u001b[39m,\n\u001b[1;32m      5\u001b[0m     \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mrandom_field\u001b[39m\u001b[38;5;124m\"\u001b[39m: \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mrandom value\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m      6\u001b[0m }\n\u001b[1;32m      8\u001b[0m model \u001b[38;5;241m=\u001b[39m ChatAnthropic(model\u001b[38;5;241m=\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mclaude-3-5-sonnet-20240620\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[0;32m---> 10\u001b[0m \u001b[43mmodel\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43minvoke\u001b[49m\u001b[43m(\u001b[49m\u001b[43m[\u001b[49m\u001b[43muncoercible_message\u001b[49m\u001b[43m]\u001b[49m\u001b[43m)\u001b[49m\n",
+      "File \u001b[0;32m~/langchain/oss-py/libs/core/langchain_core/language_models/chat_models.py:287\u001b[0m, in \u001b[0;36mBaseChatModel.invoke\u001b[0;34m(self, input, config, stop, **kwargs)\u001b[0m\n\u001b[1;32m    275\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21minvoke\u001b[39m(\n\u001b[1;32m    276\u001b[0m     \u001b[38;5;28mself\u001b[39m,\n\u001b[1;32m    277\u001b[0m     \u001b[38;5;28minput\u001b[39m: LanguageModelInput,\n\u001b[0;32m   (...)\u001b[0m\n\u001b[1;32m    281\u001b[0m     \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mkwargs: Any,\n\u001b[1;32m    282\u001b[0m ) \u001b[38;5;241m-\u001b[39m\u001b[38;5;241m>\u001b[39m BaseMessage:\n\u001b[1;32m    283\u001b[0m     config \u001b[38;5;241m=\u001b[39m ensure_config(config)\n\u001b[1;32m    284\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m cast(\n\u001b[1;32m    285\u001b[0m         ChatGeneration,\n\u001b[1;32m    286\u001b[0m         \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39mgenerate_prompt(\n\u001b[0;32m--> 287\u001b[0m             [\u001b[38;5;28;43mself\u001b[39;49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43m_convert_input\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;28;43minput\u001b[39;49m\u001b[43m)\u001b[49m],\n\u001b[1;32m    288\u001b[0m             stop\u001b[38;5;241m=\u001b[39mstop,\n\u001b[1;32m    289\u001b[0m             callbacks\u001b[38;5;241m=\u001b[39mconfig\u001b[38;5;241m.\u001b[39mget(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mcallbacks\u001b[39m\u001b[38;5;124m\"\u001b[39m),\n\u001b[1;32m    290\u001b[0m             tags\u001b[38;5;241m=\u001b[39mconfig\u001b[38;5;241m.\u001b[39mget(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mtags\u001b[39m\u001b[38;5;124m\"\u001b[39m),\n\u001b[1;32m    291\u001b[0m             metadata\u001b[38;5;241m=\u001b[39mconfig\u001b[38;5;241m.\u001b[39mget(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mmetadata\u001b[39m\u001b[38;5;124m\"\u001b[39m),\n\u001b[1;32m    292\u001b[0m             run_name\u001b[38;5;241m=\u001b[39mconfig\u001b[38;5;241m.\u001b[39mget(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mrun_name\u001b[39m\u001b[38;5;124m\"\u001b[39m),\n\u001b[1;32m    293\u001b[0m             run_id\u001b[38;5;241m=\u001b[39mconfig\u001b[38;5;241m.\u001b[39mpop(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mrun_id\u001b[39m\u001b[38;5;124m\"\u001b[39m, \u001b[38;5;28;01mNone\u001b[39;00m),\n\u001b[1;32m    294\u001b[0m             \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mkwargs,\n\u001b[1;32m    295\u001b[0m         )\u001b[38;5;241m.\u001b[39mgenerations[\u001b[38;5;241m0\u001b[39m][\u001b[38;5;241m0\u001b[39m],\n\u001b[1;32m    296\u001b[0m     )\u001b[38;5;241m.\u001b[39mmessage\n",
+      "File \u001b[0;32m~/langchain/oss-py/libs/core/langchain_core/language_models/chat_models.py:267\u001b[0m, in \u001b[0;36mBaseChatModel._convert_input\u001b[0;34m(self, input)\u001b[0m\n\u001b[1;32m    265\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m StringPromptValue(text\u001b[38;5;241m=\u001b[39m\u001b[38;5;28minput\u001b[39m)\n\u001b[1;32m    266\u001b[0m \u001b[38;5;28;01melif\u001b[39;00m \u001b[38;5;28misinstance\u001b[39m(\u001b[38;5;28minput\u001b[39m, Sequence):\n\u001b[0;32m--> 267\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m ChatPromptValue(messages\u001b[38;5;241m=\u001b[39m\u001b[43mconvert_to_messages\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;28;43minput\u001b[39;49m\u001b[43m)\u001b[49m)\n\u001b[1;32m    268\u001b[0m \u001b[38;5;28;01melse\u001b[39;00m:\n\u001b[1;32m    269\u001b[0m     msg \u001b[38;5;241m=\u001b[39m (\n\u001b[1;32m    270\u001b[0m         \u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mInvalid input type \u001b[39m\u001b[38;5;132;01m{\u001b[39;00m\u001b[38;5;28mtype\u001b[39m(\u001b[38;5;28minput\u001b[39m)\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m. \u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m    271\u001b[0m         \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mMust be a PromptValue, str, or list of BaseMessages.\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[1;32m    272\u001b[0m     )\n",
+      "File \u001b[0;32m~/langchain/oss-py/libs/core/langchain_core/messages/utils.py:348\u001b[0m, in \u001b[0;36mconvert_to_messages\u001b[0;34m(messages)\u001b[0m\n\u001b[1;32m    346\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28misinstance\u001b[39m(messages, PromptValue):\n\u001b[1;32m    347\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m messages\u001b[38;5;241m.\u001b[39mto_messages()\n\u001b[0;32m--> 348\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43m[\u001b[49m\u001b[43m_convert_to_message\u001b[49m\u001b[43m(\u001b[49m\u001b[43mm\u001b[49m\u001b[43m)\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;28;43;01mfor\u001b[39;49;00m\u001b[43m \u001b[49m\u001b[43mm\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;129;43;01min\u001b[39;49;00m\u001b[43m \u001b[49m\u001b[43mmessages\u001b[49m\u001b[43m]\u001b[49m\n",
+      "File \u001b[0;32m~/langchain/oss-py/libs/core/langchain_core/messages/utils.py:348\u001b[0m, in \u001b[0;36m<listcomp>\u001b[0;34m(.0)\u001b[0m\n\u001b[1;32m    346\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28misinstance\u001b[39m(messages, PromptValue):\n\u001b[1;32m    347\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m messages\u001b[38;5;241m.\u001b[39mto_messages()\n\u001b[0;32m--> 348\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m [\u001b[43m_convert_to_message\u001b[49m\u001b[43m(\u001b[49m\u001b[43mm\u001b[49m\u001b[43m)\u001b[49m \u001b[38;5;28;01mfor\u001b[39;00m m \u001b[38;5;129;01min\u001b[39;00m messages]\n",
+      "File \u001b[0;32m~/langchain/oss-py/libs/core/langchain_core/messages/utils.py:321\u001b[0m, in \u001b[0;36m_convert_to_message\u001b[0;34m(message)\u001b[0m\n\u001b[1;32m    319\u001b[0m     \u001b[38;5;28;01mexcept\u001b[39;00m \u001b[38;5;167;01mKeyError\u001b[39;00m \u001b[38;5;28;01mas\u001b[39;00m e:\n\u001b[1;32m    320\u001b[0m         msg \u001b[38;5;241m=\u001b[39m \u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mMessage dict must contain \u001b[39m\u001b[38;5;124m'\u001b[39m\u001b[38;5;124mrole\u001b[39m\u001b[38;5;124m'\u001b[39m\u001b[38;5;124m and \u001b[39m\u001b[38;5;124m'\u001b[39m\u001b[38;5;124mcontent\u001b[39m\u001b[38;5;124m'\u001b[39m\u001b[38;5;124m keys, got \u001b[39m\u001b[38;5;132;01m{\u001b[39;00mmessage\u001b[38;5;132;01m}\u001b[39;00m\u001b[38;5;124m\"\u001b[39m\n\u001b[0;32m--> 321\u001b[0m         \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(msg) \u001b[38;5;28;01mfrom\u001b[39;00m \u001b[38;5;21;01me\u001b[39;00m\n\u001b[1;32m    322\u001b[0m     _message \u001b[38;5;241m=\u001b[39m _create_message_from_message_type(\n\u001b[1;32m    323\u001b[0m         msg_type, msg_content, \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mmsg_kwargs\n\u001b[1;32m    324\u001b[0m     )\n\u001b[1;32m    325\u001b[0m \u001b[38;5;28;01melse\u001b[39;00m:\n",
+      "\u001b[0;31mValueError\u001b[0m: Message dict must contain 'role' and 'content' keys, got {'role': 'HumanMessage', 'random_field': 'random value'}"
+     ]
+    }
+   ],
+   "source": [
+    "from langchain_anthropic import ChatAnthropic\n",
+    "\n",
+    "uncoercible_message = {\"role\": \"HumanMessage\", \"random_field\": \"random value\"}\n",
+    "\n",
+    "model = ChatAnthropic(model=\"claude-3-5-sonnet-20240620\")\n",
+    "\n",
+    "model.invoke([uncoercible_message])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Troubleshooting\n",
+    "\n",
+    "The following may help resolve this error:\n",
+    "\n",
+    "- Ensure that all inputs to chat models are an array of LangChain message classes or a supported message-like.\n",
+    "  - Check that there is no stringification or other unexpected transformation occuring.\n",
+    "- Check the error's stack trace and add log or debugger statements."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/docs/troubleshooting/errors/MODEL_AUTHENTICATION.mdx

@@ -0,0 +1,18 @@
+# MODEL_AUTHENTICATION
+
+Your model provider is denying you access to their service.
+
+## Troubleshooting
+
+The following may help resolve this error:
+
+- Confirm that your API key or other credentials are correct.
+- If you are relying on an environment variable to authenticate, confirm that the variable name is correct and that it has a value set.
+  - Note that environment variables can also be set by packages like `dotenv`.
+  - For models, you can try explicitly passing an `api_key` parameter to rule out any environment variable issues like this:
+
+```python
+model = ChatOpenAI(api_key="YOUR_KEY_HERE")
+```
+
+- If you are using a proxy or other custom endpoint, make sure that your custom provider does not expect an alternative authentication scheme.

docs/docs/troubleshooting/errors/MODEL_NOT_FOUND.mdx

@@ -0,0 +1,10 @@
+# MODEL_NOT_FOUND
+
+The model name you have specified is not acknowledged by your provider.
+
+## Troubleshooting
+
+The following may help resolve this error:
+
+- Double check the model string you are passing in.
+- If you are using a proxy or other alternative host with a model wrapper, confirm that the permitted model names are not restricted or altered.

docs/docs/troubleshooting/errors/MODEL_RATE_LIMIT.mdx

@@ -0,0 +1,13 @@
+# MODEL_RATE_LIMIT
+
+You have hit the maximum number of requests that a model provider allows over a given time period and are being temporarily blocked.
+Generally, this error is temporary and your limit will reset after a certain amount of time.
+
+## Troubleshooting
+
+The following may help resolve this error:
+
+- Contact your model provider and ask for a rate limit increase.
+- If many of your incoming requests are the same, utilize [model response caching](/docs/how_to/chat_model_caching/).
+- Spread requests across different providers if your application allows it.
+- Use a [`rate_limiter`](/docs/how_to/chat_model_rate_limiting/) to control the rate of requests to the model.