cartflows / docs / wiki / Troubleshooting-FAQ.md

Troubleshooting-FAQ.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/Troubleshooting-FAQ.md

247 lines 6.4 KB

Raw Download Zip

1	# Troubleshooting & FAQ
2
3	Common issues, gotchas, and their solutions for CartFlows development and deployment.
4
5	---
6
7	## Development Gotchas
8
9	### 1. Built assets are committed — always rebuild before committing
10
11	Issue: React JS/CSS changes look fine locally but aren't reflected after deployment.
12
13	Cause: `admin-core/assets/build/` is tracked in git. If you change source files under `admin-core/assets/src/` but don't rebuild, the deployed code will have stale compiled assets.
14
15	Fix:
16	```bash
17	npm run build
18	git add admin-core/assets/build/
19	```
20
21	Always run `npm run build` before committing any JS or SCSS changes.
22
23	---
24
25	### 2. Two webpack configs — use `npm run all-builds` for full builds
26
27	Issue: Changes to the setup wizard don't appear after running `npm run build`.
28
29	Cause: There are two separate webpack configurations:
30	- Main apps (editor + settings): default `wp-scripts` config
31	- Setup wizard: `wizard-webpack-config.js`
32
33	`npm run build` only builds the main apps.
34
35	Fix:
36	```bash
37	npm run all-builds # Builds all three (editor, settings, wizard)
38	# or
39	npm run wizard-build # Builds the wizard only
40	```
41
42	---
43
44	### 3. RTL CSS files were intentionally removed
45
46	Issue: Build errors or missing RTL file warnings.
47
48	Cause: `editor-app-rtl.css` and `settings-app-rtl.css` were removed from the build output. These files no longer exist and should not be referenced.
49
50	Fix: Do not re-add RTL CSS references unless this is an intentional feature addition approved by the team.
51
52	---
53
54	### 4. `wc_clean` as a sanitizer
55
56	Issue: PHPCS reports `wc_clean()` as an unrecognized sanitizer.
57
58	Cause: If running PHPCS without the project's `phpcs.xml.dist` config (e.g., specifying a different config file).
59
60	Fix: Always run PHPCS using the project's config:
61	```bash
62	composer lint
63	# or
64	vendor/bin/phpcs --standard=phpcs.xml.dist
65	```
66
67	`wc_clean` is registered as a custom sanitizer in `phpcs.xml.dist`.
68
69	---
70
71	### 5. Libraries directory — do not delete
72
73	Issue: Plugin errors after running `composer install --no-dev` or manual cleanup.
74
75	Cause: `libraries/` contains Composer-installed BSF packages (analytics, notices, nps-survey) that are committed to the repo. They may appear as "unused" to some tools.
76
77	Fix: Never delete `libraries/`. It is a required directory containing vendored packages.
78
79	---
80
81	### 6. Pre-commit hook blocking commits
82
83	Issue: `git commit` fails with linting errors.
84
85	Cause: `npm install` installs a git pre-commit hook in `.git/hooks/pre-commit` that runs linting before every commit.
86
87	Fix:
88	```bash
89	# Fix the reported violations, then commit again
90	composer lint
91	npm run lint-js
92	# After fixing:
93	git commit -m "fix: resolve linting violations"
94	```
95
96	Only bypass with `--no-verify` if explicitly approved:
97	```bash
98	git commit --no-verify -m "..." # Only with team approval
99	```
100
101	---
102
103	### 7. PHPStan stubs out of date
104
105	Issue: PHPStan reports false positives for CartFlows classes after significant class changes.
106
107	Cause: The stubs at `tests/php/stubs/cf-stubs.php` reflect an older class structure.
108
109	Fix:
110	```bash
111	composer update-stubs
112	```
113
114	---
115
116	## Common Plugin Issues
117
118	### Checkout page shows default WooCommerce layout
119
120	Cause: The step is not correctly assigned to a flow, or the CartFlows frontend is not loading.
121
122	Checks:
123	1. Verify the page/post is assigned as a `wcf-step` within a `wcf-flow`
124	2. Check `Appearance → Themes` — some themes override templates in ways that conflict with CartFlows
125	3. Check for JavaScript errors in the browser console
126	4. Ensure WooCommerce is active and up to date
127
128	---
129
130	### Admin page shows blank or broken React app
131
132	Cause: JS bundle loading error, usually due to:
133	- Missing build files
134	- Conflicting JavaScript from another plugin
135	- Browser console JavaScript error
136
137	Checks:
138	1. Open browser DevTools → Console tab and look for JS errors
139	2. Verify `admin-core/assets/build/editor-app.js` exists
140	3. Disable other plugins to check for conflicts
141	4. Try a different browser or incognito mode
142
143	---
144
145	### AJAX actions not working (403 or empty response)
146
147	Cause: Nonce verification failing.
148
149	Checks:
150	1. Ensure the nonce is being sent with the AJAX request
151	2. Check if any security plugin is blocking `admin-ajax.php`
152	3. Verify the nonce was generated with the correct action name
153	4. Check server logs for PHP errors
154
155	---
156
157	### REST API returning 401 Unauthorized
158
159	Cause: The `X-WP-Nonce` header is missing or expired.
160
161	Fix:
162	- Nonces expire after 12–24 hours. Page reloads regenerate the nonce.
163	- Ensure `@wordpress/api-fetch` is configured with the nonce middleware:
164
165	```js
166	import apiFetch from '@wordpress/api-fetch';
167	apiFetch.use( apiFetch.createNonceMiddleware( wcfEditorAppData.nonce ) );
168	```
169
170	---
171
172	### Template import fails or stalls
173
174	Cause: The importer uses background processing. Issues arise when:
175	- PHP `max_execution_time` is too short
176	- Memory limit is exceeded
177	- The CartFlows API is unreachable
178
179	Fix:
180	1. Check PHP error log
181	2. Increase `max_execution_time` and `memory_limit` in `php.ini`
182	3. Try importing a single template instead of a full flow
183
184	---
185
186	### E2E tests failing on fresh wp-env setup
187
188	Cause: wp-env environment not fully initialised.
189
190	Fix:
191	```bash
192	# Clean restart
193	npm run env:clean
194	npm run env:start
195
196	# Then run tests
197	npm run test:e2e
198	```
199
200	---
201
202	## Performance Issues
203
204	### Admin React app loads slowly
205
206	Cause: Large JS bundle or unoptimised assets.
207
208	Checks:
209	1. Ensure you're using the production build (`npm run build`), not the dev build
210	2. Check for unminified assets — `editor-app.js` should be minified in production
211
212	---
213
214	### Frontend checkout page loads slowly
215
216	Cause: Excessive WooCommerce hooks or theme conflicts.
217
218	Checks:
219	1. Use a performance profiler (Query Monitor plugin)
220	2. Check for N+1 database queries in the order review section
221	3. Disable the CartFlows order bump and re-test to isolate
222
223	---
224
225	## Getting Help
226
227	1. Check this wiki — search for your topic
228	2. Check the [](Troubleshooting-FAQTroubleshooting-FAQ](Troubleshooting-FAQ](Troubleshooting-FAQ) (you are here)
229	3. Review the [](WordPress-Coding-StandardsWordPress-Coding-Standards](WordPress-Coding-Standards](WordPress-Coding-Standards) for code issues
230	4. Open a GitHub issue with:
231	- WordPress version
232	- WooCommerce version
233	- CartFlows version
234	- PHP version
235	- Steps to reproduce
236	- Error messages / screenshots
237
238	---
239
240	## Related Pages
241
242	- [](Environment-ConfigurationEnvironment-Configuration](Environment-Configuration](Environment-Configuration)
243	- [](Build-SystemBuild-System](Build-System](Build-System)
244	- [](Testing-GuideTesting-Guide](Testing-Guide](Testing-Guide)
245	- [](WordPress-Coding-StandardsWordPress-Coding-Standards](WordPress-Coding-Standards](WordPress-Coding-Standards)
246	- [](Architecture-OverviewArchitecture-Overview](Architecture-Overview](Architecture-Overview)
247