Debugging Tools

When a transaction fails, a contract goes missing, or your application behaves unexpectedly, Canton provides several tools to investigate. This page covers the debugging tools available and common workflows for diagnosing issues.

dpm test Output

dpm test runs your Daml Script tests and reports results to the terminal. When a test fails, the output includes:

The script name and the line where the failure occurred
The error type (e.g., ContractNotFound, AuthorizationError, PreconditionFailed)
For assertion failures, the expected and actual values

Read the error message carefully — Daml errors are specific. A ContractNotFound means the contract ID you referenced has been archived or never existed for your party. An AuthorizationError means the submitting party lacks the required signatory or controller role.

Choice Coverage

Run dpm test --show-coverage to see which choices in your templates were exercised during testing. Low coverage often correlates with untested edge cases. If a choice has zero coverage, consider whether your test suite exercises it.

Canton Console

The Canton Console is an interactive REPL that connects to a running Canton node. It is the most direct way to inspect ledger state during development.

Inspecting the Active Contract Set

To see what contracts currently exist for a party:

@ participant1.ledger_api.state.acs.of_party(myParty)
    res1: Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedContractEntry] = List(
      WrappedContractEntry(
        entry = ActiveContract(
          value = ActiveContract(
            createdEvent = Some(
              value = CreatedEvent(
                offset = 12L,
                nodeId = 0,
                contractId = "00106c3c66a05be02d0846bfef10992696b9c8b332d0a98356c6e9e734944f4235ca1212203570a11265eec83fda1307a66f0924b6f9aa5d29e72993633a01e0cd0129efb8",
                templateId = Some(
                  value = Identifier(
                    packageId = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba",
                    moduleName = "Iou",
                    entityName = "Iou"
                  )
                ),
                contractKey = None,
                contractKeyHash = <ByteString@8a2669d size=0 contents="">,
                createArguments = Some(
                  value = Record(
                    recordId = Some(
                      value = Identifier(
                        packageId = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba",
                        moduleName = "Iou",
                        entityName = "Iou"
                      )
                    ),
                    fields = Vector(
                      RecordField(
                        label = "payer",
                        value = Some(
                          value = Value(
                            sum = Party(
                              value = "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                            )
                          )
                        )
                      ),
                      RecordField(
                        label = "owner",
                        value = Some(
                          value = Value(
                            sum = Party(
                              value = "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                            )
                          )
                        )
                      ),
                      RecordField(
                        label = "amount",
                        value = Some(
                          value = Value(
                            sum = Record(
                              value = Record(
                                recordId = Some(
                                  value = Identifier(
                                    packageId = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba",
                                    moduleName = "Iou",
                                    entityName = "Amount"
                                  )
                                ),
                                fields = Vector(
                                  RecordField(
                                    label = "value",
                                    value = Some(value = Value(sum = Numeric(value = "100.0000000000")))
                                  ),
                                  RecordField(
                                    label = "currency",
                                    value = Some(value = Value(sum = Text(value = "EUR")))
                                  )
                                )
                              )
                            )
                          )
                        )
                      ),
                      RecordField(
                        label = "viewers",
                        value = Some(value = Value(sum = List(value = List(elements = Vector()))))
                      )
                    )
                  )
                ),
                createdEventBlob = <ByteString@8a2669d size=0 contents="">,
                interfaceViews = Vector(),
                witnessParties = Vector(
                  "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                ),
                signatories = Vector(
                  "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                ),
                observers = Vector(),
                createdAt = Some(
                  value = Timestamp(
                    seconds = 1782822795L,
    ...

@ participant1.ledger_api.state.acs.of_party(myParty).filter(_.templateId.toString.contains("Iou"))
    res2: Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedContractEntry] = List(
      WrappedContractEntry(
        entry = ActiveContract(
          value = ActiveContract(
            createdEvent = Some(
              value = CreatedEvent(
                offset = 12L,
                nodeId = 0,
                contractId = "00106c3c66a05be02d0846bfef10992696b9c8b332d0a98356c6e9e734944f4235ca1212203570a11265eec83fda1307a66f0924b6f9aa5d29e72993633a01e0cd0129efb8",
                templateId = Some(
                  value = Identifier(
                    packageId = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba",
                    moduleName = "Iou",
                    entityName = "Iou"
                  )
                ),
                contractKey = None,
                contractKeyHash = <ByteString@8a2669d size=0 contents="">,
                createArguments = Some(
                  value = Record(
                    recordId = Some(
                      value = Identifier(
                        packageId = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba",
                        moduleName = "Iou",
                        entityName = "Iou"
                      )
                    ),
                    fields = Vector(
                      RecordField(
                        label = "payer",
                        value = Some(
                          value = Value(
                            sum = Party(
                              value = "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                            )
                          )
                        )
                      ),
                      RecordField(
                        label = "owner",
                        value = Some(
                          value = Value(
                            sum = Party(
                              value = "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                            )
                          )
                        )
                      ),
                      RecordField(
                        label = "amount",
                        value = Some(
                          value = Value(
                            sum = Record(
                              value = Record(
                                recordId = Some(
                                  value = Identifier(
                                    packageId = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba",
                                    moduleName = "Iou",
                                    entityName = "Amount"
                                  )
                                ),
                                fields = Vector(
                                  RecordField(
                                    label = "value",
                                    value = Some(value = Value(sum = Numeric(value = "100.0000000000")))
                                  ),
                                  RecordField(
                                    label = "currency",
                                    value = Some(value = Value(sum = Text(value = "EUR")))
                                  )
                                )
                              )
                            )
                          )
                        )
                      ),
                      RecordField(
                        label = "viewers",
                        value = Some(value = Value(sum = List(value = List(elements = Vector()))))
                      )
                    )
                  )
                ),
                createdEventBlob = <ByteString@8a2669d size=0 contents="">,
                interfaceViews = Vector(),
                witnessParties = Vector(
                  "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                ),
                signatories = Vector(
                  "MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"
                ),
                observers = Vector(),
                createdAt = Some(
                  value = Timestamp(
                    seconds = 1782822795L,
    ...

If a contract you expect to exist is missing from the ACS, it has either been archived or your party was never a stakeholder on it.

Inspecting Transactions

To see recent transactions:

@ participant1.ledger_api.completions.list(myParty, atLeastNumCompletions = 1, beginOffsetExclusive = 0L)
    res3: Seq[com.daml.ledger.api.v2.completion.Completion] = List(
      Completion(
        commandId = "fd7130f4-c3be-48f4-bea8-b749c72b3c7c",
        status = Some(
          value = Status(
            code = 0,
            message = "",
            details = Vector(),
            unknownFields = UnknownFieldSet(fields = Map())
          )
        ),
        updateId = "1220e7bcb77aeda40038baec5e42737bf3ded06b9ae8b96fe7bfacb5ef0982fea2fe",
        userId = "CantonConsole",
        actAs = Vector("MyParty::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c"),
        submissionId = "5077bc60-b201-46a6-be9d-4b5aae5a7d05",
        deduplicationPeriod = DeduplicationOffset(value = 0L),
        traceContext = Some(
          value = TraceContext(
            traceparent = Some(value = "00-df3927b8da9feb088a981bdf8dc41bf8-53e353ddde16dd05-03"),
            tracestate = None
          )
        ),
        offset = 12L,
        synchronizerTime = Some(
          value = SynchronizerTime(
            synchronizerId = "da::122032922613929d67857e621fb13e3da49ec13883e24908404520319eee6d31fb4d",
            recordTime = Some(
              value = Timestamp(
                seconds = 1782822793L,
                nanos = 849861000,
                unknownFields = UnknownFieldSet(fields = Map())
              )
            )
          )
        ),
        paidTrafficCost = 0L,
        transactionHash = None
      )
    )

Transaction details show which contracts were created, archived, and exercised. Compare the transaction trace against your expectations to identify where logic diverged.

Uploading Packages

If you need to update your Daml packages on a running node:

@ participant1.dars.upload("dars/CantonExamples.dar")
    res4: String = "2b4b62a3503e321acd9736013530de57e028d67c9390f3af7c630f60bd816eba"

PQS SQL Queries

PQS projects ledger state into PostgreSQL tables. When you need to investigate contract state across multiple templates or trace historical events, SQL is often the fastest approach.

Finding a Contract

-- Find active contracts of a given template
SELECT contract_id, create_arguments
FROM active_contracts
WHERE template_id LIKE '%MyTemplate%';

Tracing an Archived Contract

-- Find when and why a contract was archived
SELECT contract_id, archive_event_id, effective_at
FROM contracts
WHERE template_id LIKE '%MyTemplate%'
  AND contract_id = 'your-contract-id';

Checking Event History

-- List recent events for a template
SELECT event_id, event_type, contract_id, effective_at
FROM events
WHERE template_id LIKE '%MyTemplate%'
ORDER BY effective_at DESC
LIMIT 20;

PQS queries are scoped to your party’s data. If you cannot find a contract in PQS, your party may not be a stakeholder on it.

Log Analysis

When running LocalNet or a local Sandbox, logs capture detailed information about transaction processing, validation errors, and node behavior.

Capturing Logs

In the cn-quickstart environment:

make capture-logs

This collects logs from all Docker containers into a local directory for analysis.

Using lnav

lnav is a log file viewer that handles structured logs well. It supports filtering, searching, and timeline navigation across multiple log files simultaneously.

lnav logs/*.log

Within lnav, use :filter-in to focus on specific patterns (e.g., a transaction ID or error keyword) and :filter-out to remove noise.

What to Look For

WARN and ERROR level messages — These indicate problems. Search for the transaction ID or command ID from your failing operation.
Rejection reasons — When the mediator rejects a transaction, the logs include the reason (timeout, inconsistency, authorization failure).
Connectivity issues — If your validator cannot reach the synchronizer, transactions stall. Look for connection errors or timeout messages.

Common Debugging Workflows

”Why did my transaction fail?”

Check the error returned by the Ledger API or your backend. Note the command ID.
Search the validator logs for that command ID to find the detailed rejection reason.
Common causes: insufficient authorization (wrong submitting party), contract already archived (race condition), insufficient traffic credits (check your validator’s traffic budget).

”Where is my contract?”

Query PQS or the Canton Console ACS for the contract ID or template.
If the contract is not in the ACS, check PQS for archive events — it may have been consumed by a choice.
If you never see the contract, verify that your party is a stakeholder (signatory or observer) on it. Canton’s privacy model means your party simply will not see contracts it has no stake in.

”Why can’t I see this contract?”

This is almost always a privacy question. Your party can see a contract only if it is a signatory, observer, or has received the contract through divulgence or explicit disclosure. Check the template definition to confirm your party’s role. If your party is not listed, you need to either add it as an observer in the Daml model or use explicit disclosure.

Next Steps

Development Tools Overview — Summary of all available tools
Troubleshooting — Solutions for common Canton development issues
Testing Daml Contracts — Writing effective tests to catch issues early

Get Started

Module 1: Understanding Canton

Module 2: Canton for Ethereum Developers

Module 3: Daml Smart Contracts

Module 4: Full-Stack Application Development

Module 5: Testing & Deployment

Module 6: Smart Contract Upgrades

Module 7: Production Best Practices

Deep Dives

Tooling

App Rewards

Troubleshooting

Reference

dpm test Output

Choice Coverage

Canton Console

Inspecting the Active Contract Set

Inspecting Transactions

Uploading Packages

PQS SQL Queries

Finding a Contract

Tracing an Archived Contract

Checking Event History

Log Analysis

Capturing Logs

Using lnav

What to Look For

Common Debugging Workflows

”Why did my transaction fail?”

”Where is my contract?”

”Why can’t I see this contract?”

Next Steps

​dpm test Output

​Choice Coverage

​Canton Console

​Inspecting the Active Contract Set

​Inspecting Transactions

​Uploading Packages

​PQS SQL Queries

​Finding a Contract

​Tracing an Archived Contract

​Checking Event History

​Log Analysis

​Capturing Logs

​Using lnav

​What to Look For

​Common Debugging Workflows

​”Why did my transaction fail?”

​”Where is my contract?”

​”Why can’t I see this contract?”

​Next Steps

dpm test Output

Choice Coverage

Canton Console

Inspecting the Active Contract Set

Inspecting Transactions

Uploading Packages

PQS SQL Queries

Finding a Contract

Tracing an Archived Contract

Checking Event History

Log Analysis

Capturing Logs

Using lnav

What to Look For

Common Debugging Workflows

”Why did my transaction fail?”

”Where is my contract?”

”Why can’t I see this contract?”

Next Steps