{"slug":"oip-troubleshooting","title":"OIP Troubleshooting Guide","body":"## What OIP Troubleshooting Is\n\nOIP stands for Object Invocation Protocol. Troubleshooting OIP means finding and fixing problems when you try to use OIP objects. An OIP object is a row in the miscsubjects.com directory. You invoke, or call, these objects to make them do things. If an object does not work as you expect, troubleshooting helps you understand why. This guide helps you find common issues and solve them.\n\n## Why This Build Cares About It\n\nmiscsubjects.com is a live system where many objects run. Users and other systems rely on these objects working correctly. When an invocation fails, it is important to know why. This build cares about troubleshooting because it helps ensure the system is reliable. It also helps users understand how to interact with OIP objects successfully. Knowing how to troubleshoot makes the system easier to use for everyone.\n\n## How to See or Use It Live with curl\n\nYou can use `curl` to troubleshoot OIP invocations. `curl` is a command-line tool for making network requests. An API, or Application Programming Interface, is a set of rules that lets different software programs talk to each other. OIP uses a RESTful API. REST stands for Representational State Transfer. It is a style of building web services. The miscsubjects.com API endpoint for invoking objects is `/api/dispatch`. An endpoint is a specific URL where an API can be accessed. A URL, or Uniform Resource Locator, is an address for a resource on the internet. A server is a computer program that provides services to other computer programs.\n\nHere are common troubleshooting steps:\n\n### 1. Check for Basic Invocation Errors\n\nEvery OIP invocation needs a `key` and a `body`. The `key` tells OIP which object to invoke. The `body` sends data to that object. If you forget one, the invocation will fail. You send data using `POST` or `GET` methods. `POST` is a method to send data to a server. `GET` is a method to request data from a server. JSON, or JavaScript Object Notation, is a way to store and exchange data in a human-readable format.\n\n**Example of a missing `key` (will fail):**\n```bash\ncurl -X POST https://miscsubjects.com/api/dispatch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"body\":\"This invocation will fail.\"}'\n```\nThis will likely return an error message like `{\"error\":\"Missing 'key' parameter.\"}`. This tells you exactly what is wrong.\n\n**Example of a successful invocation (for comparison):**\n```bash\ncurl -X POST https://miscsubjects.com/api/dispatch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"key\":\"echo\",\"body\":\"Hello, OIP!\"}'\n```\nThis should return a successful response, often including an `inv_ID`.\n\n### 2. Check the Invocation Receipt\n\nEvery invocation, whether successful or not, creates a receipt. A receipt is a record of an action, showing what happened. This receipt contains important details about the invocation's outcome. You can get a receipt using the `inv_ID` from your invocation response. If you did not get an `inv_ID` in the response, it means the invocation failed before a receipt could be created.\n\n**To retrieve a receipt:**\n```bash\ncurl https://miscsubjects.com/api/dispatch?receipt=YOUR_INV_ID_HERE\n```\nReplace `YOUR_INV_ID_HERE` with the actual `inv_ID` you received. The receipt will show the `status` (e.g., `success`, `error`), `output`, and any `error` messages. This is the most important tool for understanding why an object behaved in a certain way. For more details, see `/a/oip-ledger-receipts`.\n\n### 3. Verify Object Existence\n\nIf you get an error like \"Object not found\" or \"Invalid key,\" double-check the `key` you are using. The `key` must match an existing object in the miscsubjects.com directory. You can explore available objects by browsing `/api/articles` or other documentation.\n\n## How It Relates to MCP\n\nOIP differs from MCP, or Model Context Protocol, in how troubleshooting works. MCP is an open standard where an AI model connects to an MCP server over a session. The server exposes tools, resources, and prompts the model can call. MCP is NOT a content-management system. Troubleshooting in MCP might involve checking the persistent session state or the model's context. OIP, however, uses plain URLs and receipts with no persistent session. Each OIP invocation is independent. Therefore, OIP troubleshooting focuses on individual invocation parameters, the specific URL used, and the details within the invocation receipt. You do not need to worry about session state when troubleshooting OIP.\n\n## Where the Proof Lives\n\nAll OIP invocations are recorded in an append-only ledger. This ledger is accessible at `/api/dispatch`. Every entry in this ledger has a unique `inv_ID`. This `inv_ID` lets you retrieve the specific receipt for that invocation. The receipt is the definitive proof of what happened during an invocation. It shows the input, output, and any errors. You can access individual receipts by making a `GET` request to `/api/dispatch?receipt=inv_ID`. This system ensures transparency and provides a clear record for all troubleshooting efforts. For more information, see `/a/oip-ledger-receipts`.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","dynamic"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}