Component Troubleshooting
Before you follow this section, consider configuring the log level to debug for more information when troubleshooting.
When developing components, there are a few common errors that can cause your component to fail to run or properly operate. Below we'll walk through a few of these scenarios with accompanying error messages.
Failing to start a component from a local registry over HTTP
The following error can happen when attempting to start a component from a local registry server over HTTP:
2023-12-19T22:31:26.154791Z ERROR wasmcloud_host::wasmbus: failed to scale component actor_ref=127.0.0.1:5000/v2/hello:0.1.0 err=failed to fetch component
Caused by:
0: failed to fetch component under OCI reference `127.0.0.1:5000/v2/hello:0.1.0`
1: failed to fetch OCI path
2: failed to fetch OCI bytes
3: error sending request for url (https://127.0.0.1:5000/v2/): error trying to connect: received corrupt message of type InvalidContentType
To fix this error, you need to set the --allowed-insecure argument on the host.
When accessing a local registry from within a docker compose network, you should use registry:5000 (or the name of the registry container, if it differs) instead of localhost:5000.
Even though port 5000 may be available on your host's network, networking works differently within docker, and you should use the name of the container instead of localhost.
Failing to invoke a component
Missing Runtime Links
Invocations are only allowed between components and providers that have been linked. Omitting a link will result in a runtime error when the host denies the invocation:
{"error":"Host send error failed to call `wasmcloud:bus/host.call`: failed to call linked provider: unknown component call alias"}
To fix this error, make sure components and providers are linked to each other appropriately. To inspect the current set of runtime links, run:
wash get links
The command line wasmCloud shell (aka wash) attempts to safeguard against misspellings, though it is unable to determine if a particular link is between the intended component and provider.
If any of the component ID, provider ID, link name, or contract ID are misspelled or omitted, then the host will deny the invocation.
Troubleshooting invocations
Note that the following commands are experimental and may change in the future. To use them, supply the --experimental flag with each command, or set the WASH_EXPERIMENTAL environment variable to true.
wash spy
wash spy monitors all invocations to/from a given component. This can be useful for troubleshooting communication issues and identifying logic bugs. To use it, run:
wash spy <component name or ID>
You can pass the actual component ID if you wish, but for ease of use, wash will attempt to resolve the input to an ID by checking if the actor_name or call_alias fields from the component's claims contains the given string (case-insensitive). If more than one matches, then an error will be returned, indicating the options to choose from.
You can try out this command with the KV Counter example:
$ wget https://raw.githubusercontent.com/wasmCloud/examples/main/component/kvcounter/wadm.yaml
$ wash app put wadm.yaml
Successfully put manifest
$ wash app deploy kvcounter
Deployed model
$ wash spy kvcounter
Spying on component kvcounter
[2023-06-21 11:24:32.397138 -06:00]
From: HTTP Server To: kvcounter Host: NC7XZN5VJW2EOK6E565MSRY3JW2WU5ABUA6HTSPY6O7MVKGZTFCR3TDM
Operation: HttpServer.HandleRequest
Message: {
"method": "GET",
"path": "/api/counter",
"queryString": "",
"header": {
"host": [
"127.0.0.1:8081"
],
"user-agent": [
"curl/7.88.1"
],
"accept": [
"*/*"
]
},
"body": []
}
[2023-06-21 11:24:32.407787 -06:00]
From: kvcounter To: Redis KeyValue Store Host: CB6S44L4Q5IIRD4BJGQXN5TJXF4YFJXD5DOYBZOYRJP5U2GEZFKXNGD4
Operation: KeyValue.Increment
Message: {
"key": "counter:default",
"value": 1
}
This output has the timestamp the invocation was observed at, the source and target of the invocation, and the content of the invocation itself. wash spy will attempt to decode the invocation and output it to JSON, but if it is unable to, it will output the raw bytes instead.
wash capture
This command enables you to debug an issue after it occurs by capturing a window of all invocations in the lattice (1 hour by default). This is similar to many gaming tools that constantly capture your video while you game, and then with a press of a button you can save the last 60s for later use. wash capture can be useful for troubleshooting issues that are difficult to reproduce only occur in specific environments.
To use it, run:
wash capture --enable
By default, this will set up a sliding capture window of 1 hour (older invocations will be deleted). You can change this by passing the --window-size flag. For example, to set up a window of 5 minutes, you can run:
wash capture --enable --window-size 5
Once you want to inspect previous invocations, you can capture the last window by running:
wash capture
No messages received in the last second. Ending capture
Completed capture and output to file 2023-06-14T11:11:03.476732-06:00.default.washcapture
This command will run until it detects a message that is past the time you started the capture, or no new messages appear for 1s (whichever comes first). It will then create a file that contains all the messages that occurred in the last window, along with a dump of all hosts in the lattice and their inventories. This file is just a tarball, but since the structure of the tarball should not be relied upon, it has a .washcapture extension. The filename will be of the form <rfc3339 timestamp>.<lattice>.washcapture.
Using a washcapture file
You can use the wash capture replay command to replay a .washcapture file. For example:
$ wash capture replay 2023-06-14T11:11:03.476732-06:00.default.washcapture
This command will output all invocations in the order they were received. The output will look similar to below:
[2023-06-14 17:10:15.131165 +00:00:00]
From: VAG3QITQQ2ODAOWB5TTQSDJ53XK3SHBEIFNK4AYJ5RKAX2UNSCAPHA5M To: MCFMFDWFHGKELOXPCNCDXKK5OFLHBVEWRAOXR5JSQUD2TOFRE3DFPM7E Host: NC7XZN5VJW2EOK6E565MSRY3JW2WU5ABUA6HTSPY6O7MVKGZTFCR3TDM
Operation: HttpServer.HandleRequest
Message: {
"method": "GET",
"path": "/api/counter",
"queryString": "",
"header": {
"host": [
"127.0.0.1:8081"
],
"user-agent": [
"curl/7.88.1"
],
"accept": [
"*/*"
]
},
"body": []
}
[2023-06-14 17:10:15.151724 +00:00:00]
From: MCFMFDWFHGKELOXPCNCDXKK5OFLHBVEWRAOXR5JSQUD2TOFRE3DFPM7E To: VAZVC4RX54J2NVCMCW7BPCAHGGG5XZXDBXFUMDUXGESTMQEJLC3YVZWB Host: CB6S44L4Q5IIRD4BJGQXN5TJXF4YFJXD5DOYBZOYRJP5U2GEZFKXNGD4
Operation: KeyValue.Increment
Message: {
"key": "counter:default",
"value": 1
}
This output has the timestamp the invocation was observed, the source and target of the invocation, and the content of the invocation itself. wash spy will attempt to decode the invocation and output it to JSON, but if it is unable to, it will output the raw bytes instead. Because this can be done offline, wash capture does not attempt to fetch friendly names for each of the providers and components.
You can also filter the output by passing the --provider-id and --component-id flags. If you pass just one of the flags, it will filter all invocations that were set to or from that component/provider. If both flags are passed, it will only output invocations between that component and provider.
Lastly, there is an interactive mode, which can be enabled by passing the --interactive flag. You can then step through each invocation by pressing the Enter key.
Using the NATS CLI
You can interact directly with NATS using the NATS CLI. Find instructions to install the CLI on the NATS CLI GitHub repo.
You can use the nats subscribe (or nats sub) command to subscribe to a NATS subject. Subscribing with the NATS CLI client can be a useful way to test invocations.
You can find a full reference for nats subscribe with nats subscribe help.
To listen for all invocations that are sent to a particular component:
nats sub "{lattice}.{component_id}.wrpc.>"
You can also watch all wRPC traffic with:
nats sub '*.*.wrpc.>'