# Troubleshooting

Use this reference when live extraction or documentation quality checks fail.

## Browser and session

- Browser-harness daemon may persist across commands. Always set `BU_CDP_URL` in the same command as `browser-harness`.
- Clear stale daemons before a new task.
- Use an isolated Chrome profile and port. Never attach to the user's daily browser.
- If headless screenshots are blank, wait and capture again.
- CloakBrowser-style Playwright wrappers may not expose the CDP endpoint expected by browser-harness.

## Login

- E10 input fields often require native setter plus `input`, `change`, and `blur` events.
- Locate inputs through `data-id`, not placeholder or name attributes.
- Captcha is expected to be four digits. If fewer digits are recognized, refresh the captcha and retry.
- After login, verify the URL is no longer the login page before extracting docs.

## OpenAPI pages

- E10 docs are React SPA pages. Wait after navigation before extracting `document.body.innerText`.
- `curl` may return only the shell HTML and is not reliable for page content.
- Documentation category entries are often `<a>` tags; extract hrefs and navigate directly.
- Distinguish “新增流程” from “创建流程实例”. Use the workflow-instance API for external workflow submission.

## Workflow and forms

- Prefer internal read-only APIs over UI clicking.
- `workflowId` is not `formId`.
- Workflow names and form names may differ. Use core keywords.
- `pageNo` and `pageSize` are the expected pagination keys, not `page` and `size`.
- `formFieldSearchEntity` is required for field queries.
- If `formTableId` returns no main-table fields, retry without `formTableId`.
- Use `getForm` to detect detail tables before trying UI switching.

## UI fallback

- JS `click()` may fail on workflow cards. Coordinate click may be required.
- Multiple menu items have similar names. Confirm the current page and tab before extracting fields.
- `字段设置` and `字段管理` are not the same.
- Pagination can be unreliable; prefer requesting enough records through the internal field API.

## Output quality

- If requiredness cannot be confirmed, write `需确认`.
- If field type mapping is unclear, describe the known field type and mark payload mapping as needing confirmation.
- If a workflow has no detail table, omit the detail-table section entirely.
- If generated documentation contains internal API paths or database names, revise before delivery.